# groff_diff - differences between GNU roff and AT&T troff - man(7) - [phpMan] [_groff_diff_(7)](https://www.chedong.com/phpMan.php/man/groffdiff/7/markdown) Miscellaneous Information Manual [_groff_diff_(7)](https://www.chedong.com/phpMan.php/man/groffdiff/7/markdown) ## Name groff_diff - differences between GNU _roff_ and AT&T _troff_ ## Description The GNU _roff_ text processing system, _groff_, is an extension of AT&T _troff_, the typesetting system originating in Unix systems of the 1970s. _groff_ removes many arbitrary limitations and adds features, both to the input language and to the page description language output by the _troff_ formatter. Differences arising from _groff_'s implementation of AT&T _troff_ features are also noted. See [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) for background. ## Language GNU _troff_ features identifiers of arbitrary length; supports color output, non-integral type sizes, and user-defined characters; adds more conditional expression operators; recognizes additional scaling units and numeric operators; enables general file I/O (in “unsafe mode” only); and exposes more formatter state. ### Long names GNU _troff_ introduces many new requests; with three exceptions (**cp**, **do**, **rj**), they have names longer than two characters. The names of registers, fonts, strings/macros/diversions, envi‐ ronments, special characters, streams, and colors can be of any length. Anywhere AT&T _troff_ supports a parameterized escape sequence that uses an opening parenthesis “(” to introduce a two-character argument, _groff_ supports a square-bracketed form “[]” where the argument within can be of arbitrary length. ### Font families, abstract styles, and translation GNU _troff_ can group text typefaces into _families_ containing each of the styles “**R**”, “**I**”, “**B**”, and “**BI**”. So that a document need not be coupled to a specific font family, an output device can associate a style in the abstract sense with a mounting position. Thus the default fam‐ ily can be combined with a style dynamically, producing a _resolved_ _font_ _name._ A document can _translate,_ or remap, fonts with the **ftr **request. Applying the requests **cs**, **bd**, **tkf**, **uf**, or **fspecial **to an abstract style affects the member of the default family corresponding to that style. The default family can be set with the **fam** request or **-f **command-line option. The **styles **directive in the output device's _DESC_ file controls which mounting positions (if any) are initially associated with abstract styles rather than fonts, and the **sty **request can update this association. ### 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 figures are drawn, and the _fill_ _color,_ which paints the interior of filled geo‐ metric figures. The **color**, **defcolor**, **gcolor**, and **fcolor **requests; **\m **and **\M **escape se‐ quences; and **.color**, **.m**, and **.M **registers exercise color support. ### Fractional type sizes and new scaling units AT&T _troff_ interpreted all type size measurements in points. Combined with integer arith‐ metic, this design choice made it impossible to support, for instance, ten and a half-point type. In GNU _troff_, an output device can select a scaling factor that subdivides a point into “scaled points”. A type size expressed in scaled points can thus represent a non-inte‐ gral type size. A _scaled_ _point_ is equal to 1/_sizescale_ points, where _sizescale_ is specified in the device de‐ scription file, _DESC_, and defaults to 1; see [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown). Requests and escape sequences in GNU _troff_ interpret arguments that represent a type size in points, which the formatter mul‐ tiplies by _sizescale_ and converts to an integer. Arguments treated in this way comprise those to the escape sequences **\H **and **\s**, to the request **ps**, the third argument to the **cs **re‐ quest, and the second and fourth arguments to the **tkf **request. Scaled points may be speci‐ fied explicitly with the **z **scaling unit. In GNU _troff_, the register **\n[.s] **can interpolate a non-integral type size. The register **\n[.ps] **interpolates the type size in scaled points. For example, if _sizescale_ is 1000, then a scaled point is one thousandth of a point. Conse‐ quently, “**.ps 10.5**” is synonymous with “**.ps 10.5z**”; both set the type size to 10,500 scaled points, or 10.5 points. It makes no sense to use the “**z**” scaling unit in a numeric expression whose default scaling unit is neither “**u**” nor “**z**”, so GNU _troff_ disallows this. Similarly, it is nonsensical to use a scaling unit other than “**z**” or “**u**” in a numeric expression whose default scaling unit is “**z**”, so GNU _troff_ disallows this as well. Another new scaling unit, “**s**”, multiplies by the number of basic units in a scaled point. Thus, “**\n[.ps]s**” is equal to “**1m**” by definition. Do not confuse the “**s**” and “**z**” scaling units. Output devices may be limited in the type sizes they can employ. The **.s **and **.ps **registers represent the type size as selected by the output driver as it understands a device's capa‐ bility. The last _requested_ type size is interpolated in scaled points by the read-only reg‐ ister **.psr **and in points as a decimal fraction by the read-only string-valued register **.sr**. Both are associated with the environment. For example, if a type size of 10.95 points is re‐ quested, and the nearest size permitted by a **sizes **request (or by the **sizes **or **sizescale **di‐ rectives in the device's _DESC_ file) is 11 points, the output driver uses the latter value. A further two new measurement units available in _groff_ are “**M**”, which indicates hundredths of an em, and “**f**”, which multiplies by 65,536. The latter provides convenient fractions for color definitions with the **defcolor **request. For example, 0.5f equals 32768u. ### Numeric expressions GNU _troff_ permits spaces in a numeric expression within parentheses, and offers three new op‐ erators. _e1_**>?_**e2_ Interpolate the greater of _e1_ and _e2_. _e1_** } .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016] The class “**[prepunctx]**” thus contains the contents of the class “**[prepunct]**” and char‐ acters in the range U+2013–U+2016. If you want to include “**-**” in a class, it must be the first character value in the ar‐ gument list, otherwise it gets misinterpreted as part of the range syntax. It is not possible to use class names as end points of range definitions. A typical use of the **class **request is to control line-breaking and hyphenation rules as defined by the **cflags **request. For example, to inhibit line breaks before the characters belonging to the “**[prepunctx]**” class defined in the previous example, you can write the following. .cflags 2 \C'[prepunctx]' **.close _**stream_ Close the stream named _stream_, invalidating it as an argument to the **write **request. See **open**. **.composite _**c1_ _c2_ Map character name _c1_ to character name _c2_ when _c1_ is a combining component in a com‐ posite glyph. Typically, this remaps a spacing glyph to a combining one. ### .continue Skip the remainder of a “**while**” loop's body, immediately starting the next iteration. See **break**. **.color _**n_ If _n_ is non-zero or missing, enable colors (the default), otherwise disable them. **.cp _**n_ If _n_ is non-zero or missing, enable compatibility mode, otherwise disable it. In com‐ patibility mode, long names are not recognized, and the incompatibilities they cause do not arise. **.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 components), “**cmyk**” (four components), or “**gray**” (one component). “**grey**” is accepted as a synonym of “**gray**”. The color components can be encoded as a hexadecimal value starting with **# **or **##**. The former indicates that each component is in the range 0–255 (0–FF), the latter the range 0–65535 (0–FFFF). Alternatively, each color component can be specified as a decimal fraction in the range 0–1, interpreted using a default scaling unit of “**f**”, which multiplies its value by 65,536 (but clamps it at 65,535). Each output device has a color named “**default**”, which cannot be redefined. A device's default stroke and fill colors are not necessarily the same. **.de1 _**name_ [_end-name_] Define a macro to be interpreted with compatibility mode disabled. When _name_ is called, compatibility mode enablement status is saved; it is restored when the call completes. **.dei _**name_ [_end-name_] Define macro indirectly, with the name of the macro to be defined in string _name_ and the name of the end macro terminating its definition in string _end-name_. **.dei1 _**name_ [_end-name_] As **dei**, but compatibility mode is disabled while the definition of the macro named in string _name_ is interpreted. **.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 the embedding of leading spaces. **.devicem _**name_ Write contents of macro or string _name_ to _troff_ output as a device control command. **.do _**name_ [_arg_ ...] Interpret the string, request, diversion, or macro _name_ (along with any arguments) with compatibility mode disabled. Compatibility mode is restored (only if it was ac‐ tive) when the _expansion_ of _name_ is interpreted; that is, the restored compatibility state applies to the contents of the macro, string, or diversion _name_ as well as data read from files or pipes if _name_ is any of the **so**, **soquiet**, **mso**, **msoquiet**, or **pso **re‐ quests. For example, .de mac1 FOO .. .de1 mac2 groff .mac1 .. .de mac3 compatibility .mac1 .. .de ma \\$1 .. .cp 1 .do mac1 .do mac2 \" mac2, defined with .de1, calls "mac1" .do mac3 \" mac3 calls "ma" with argument "c1" .do mac3 \[ti] \" groff syntax accepted in .do arguments results in FOO groff FOO compatibility c1 ~ as output. **.ds1 _**name_ _contents_ As **ds**, but compatibility mode is disabled while _name_ is interpreted: a “compatibility save” token is inserted at the beginning of _contents_, and a “compatibility restore” token after it. **.ecr **Restore the escape character saved with **ecs**, or set escape character to “**\**” if none has been saved. **.ecs **Save the current escape character. **.evc _**env_ Copy the properties of environment _env_ to the current environment, except for the fol‐ lowing data. • a partially collected line, if present; • the interruption status of the previous input line (due to use of the **\c **escape se‐ quence); • the count of remaining lines to center, to right-justify, or to underline (with or without underlined spaces)—these are set to zero; • the activation status of temporary indentation; • input traps and their associated data; • the activation status of line numbering (which can be reactivated with “**.nm +0**”); and • the count of consecutive hyphenated lines (set to zero). **.fam **[_family_] Set default font family to _family_. If no argument is given, the previous font family is selected, or the formatter's default family if there is none. The formatter's de‐ fault font family is “T” (Times), but it can be overridden by the output device—see [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown). The default font family is associated with the environment. See **\F**. **.fchar _**c_ _contents_ Define fallback character _c_ as _contents_. The syntax of this request is the same as the **char **request; the difference is that a character defined with **char **hides a glyph with the same name in the selected font, whereas characters defined with **fchar **are checked only if _c_ isn't found in the selected font. This test happens before special fonts are searched. **.fcolor _**color_ Set the fill color to _color_. Without an argument, the previous fill color is se‐ lected. **.fschar _**f_ _c_ _contents_ Define fallback special character _c_ for font _f_ as _contents_. A character defined by **fschar **is located after the list of fonts declared with **fspecial **is searched but be‐ fore those declared with the “**special**” request. **.fspecial _**f_ _s1_ _s2_ ... When font _f_ is selected, fonts _s1_, _s2_, ... are treated as special; that is, they are searched for glyphs not found in _f_. Any fonts specified in the “**special**” request are searched after _s1_, _s2_, and so on. Without _s_ arguments, **fspecial **clears the list of fonts treated as special when _f_ is selected. **.ftr _**f_ _g_ Translate font _f_ to _g_. Whenever a font named _f_ is referred to in an **\f **escape se‐ quence, in the **F **and **S **conditional expression operators, or in the **ft**, **ul**, **bd**, **cs**, **tkf**, **special**, **fspecial**, **fp**, or **sty **requests, font _g_ is used. If _g_ is missing or iden‐ tical to _f_, then font _f_ is not translated. **.fzoom _**f_ _zoom_ Set zoom factor _zoom_ for font _f_. _zoom_ must a non-negative integer multiple of 1/1000th. If it is missing or is equal to zero, it means the same as 1000, namely no magnification. _f_ must be a resolved font name, not an abstract style. **.gcolor _**color_ Set the stroke color to _color_. Without an argument, the previous stroke color is se‐ lected. **.hcode _**c1_ _code1_ [_c2_ _code2_] ... Set the hyphenation code of character _c1_ to _code1_, that of _c2_ to _code2_, and so on. A hyphenation code must be an ordinary character (not a special character escape se‐ quence) other than a digit. The request is ignored if given no arguments. For hyphenation to work, hyphenation codes must be set up. At startup, _groff_ assigns hyphenation codes to the letters “a–z” (mapped to themselves), to the letters “A–Z” (mapped to “a–z”), and zero to all other characters. Normally, hyphenation patterns contain only lowercase letters which should be applied regardless of case. In other words, they assume that the words “ABBOT” and “Abbot” should be hyphenated exactly as “abbot” is. **hcode **extends this principle to letters outside the Unicode basic Latin alphabet; without it, words containing such letters won't be hyphenated properly even if the corresponding hyphenation patterns contain them. **.hla _**lang_ Set the hyphenation language to _lang_. Hyphenation exceptions specified with the **hw** request and hyphenation patterns and exceptions specified with the **hpf **and **hpfa **re‐ quests are associated with the hyphenation language. The **hla **request is usually in‐ voked by a localization file, which is in turn loaded by the _troffrc_ or _troffrc-end_ file; see the **hpf **request below. The hyphenation language is associated with the en‐ vironment. **.hlm **[_n_] Set the maximum number of consecutive hyphenated lines to _n_. If _n_ is negative, there is no maximum. If omitted, _n_ is -1. This value is associated with the environment. Only lines output from a given environment count towards the maximum associated with that environment. Hyphens resulting from **\% **are counted; explicit hyphens are not. **.hpf _**pattern-file_ Read hyphenation patterns from _pattern-file_. This file is sought in the same way that macro files are with the **mso **request or the **-m_**name_ command-line option to [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) and [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). The _pattern-file_ should have the same format as (simple) TeX pattern files. The fol‐ lowing scanning rules are implemented. • A percent sign starts a comment (up to the end of the line) even if preceded by a backslash. • “Digraphs” like **\$ **are not supported. • “**^^_**xx_” (where each _x_ is 0–9 or a–f) and **^^_**c_ (character _c_ in the code point range 0–127 decimal) are recognized; other uses of **^ **cause an error. • No macro expansion is performed. • **hpf **checks for the expression **\patterns{**...**} **(possibly with whitespace before or af‐ ter the braces). Everything between the braces is taken as hyphenation patterns. Consequently, “**{**” and “**}**” are not allowed in patterns. • Similarly, **\hyphenation{**...**} **gives a list of hyphenation exceptions. • **\endinput **is recognized also. • For backwards compatibility, if **\patterns **is missing, the whole file is treated as a list of hyphenation patterns (but the “**%**” character is still recognized as the start of a comment). Use the **hpfcode **request (see below) to map the encoding used in hyphenation pattern files to _groff_'s input encoding. 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. By default, _troffrc_ loads the localization file for English. (As of _groff_ 1.23.0, localization files for Czech (_cs_), German (_de_), English (_en_), French (_fr_), Japanese (_ja_), Swedish (_sv_), and Chinese (_zh_) exist.) For Western languages, the localization file sets the hyphenation mode and loads hyphenation patterns and ex‐ ceptions. A second call to **hpf **(for the same language) replaces the old patterns with the new ones. Invoking **hpf **causes an error if there is no hyphenation language. If no **hpf **request is specified (either in the document, in a file loaded at startup, or in a macro package), GNU _troff_ won't automatically hyphenate at all. **.hpfa _**pattern-file_ As **hpf**, except that the hyphenation patterns and exceptions from _pattern-file_ are ap‐ pended to the patterns already applied to the hyphenation language of the environment. **.hpfcode _**a_ _b_ [_c_ _d_] ... Define mapping values for character codes in pattern files. This is an older mecha‐ nism no longer used by _groff_'s own macro files; for its successor, see **hcode **above. **hpf **or **hpfa **apply the mapping after reading or appending to the active list of pat‐ terns. Its arguments are pairs of character codes—integers from 0 to 255. The re‐ quest maps character code _a_ to code _b_, code _c_ to code _d_, and so on. Character codes that would otherwise be invalid in _groff_ can be used. By default, every code maps to itself except those for letters “A” to “Z”, which map to those for “a” to “z”. **.hym **[_length_] Set the (right) hyphenation margin to _length_. If the adjustment mode is not “**b**” or “**n**”, the line is not hyphenated if it is shorter than _length_. Without an argument, the default hyphenation margin is reset to its default value, 0. The default scaling unit is “**m**”. The hyphenation margin is associated with the environment. A negative argument resets the hyphenation margin to zero, emitting a warning in category “**range**”. **.hys **[_hyphenation-space_] Suppress hyphenation of the line in adjustment modes “**b**” or “**n**”, if it can be justi‐ fied by adding no more than _hyphenation-space_ extra space to each inter-word space. Without an argument, the hyphenation space adjustment threshold is set to its default value, 0. The default scaling unit is “**m**”. The hyphenation space adjustment thresh‐ old is associated with the current environment. A negative argument resets the hy‐ phenation space adjustment threshold to zero, emitting a warning in category “**range**”. **.itc _**n_ _name_ As “**it**”, but lines interrupted with the **\c **escape sequence are not applied to the line count. **.kern _**n_ If _n_ is non-zero or missing, enable pairwise kerning (the default), otherwise disable it. **.length _**reg_ _anything_ Compute the number of characters in _anything_ and return the count in the register _reg_. If _reg_ doesn't exist, it is created. _anything_ is read in copy mode. **.ds xxx abcd\h'3i'efgh** **.length yyy \*[xxx]** **\n[yyy]** 14 **.linetabs _**n_ If _n_ is non-zero or missing, enable line-tabs mode, otherwise disable it (the de‐ fault). In this mode, tab stops are computed relative to the start of the pending output line, instead of the drawing position corresponding to the start of the input line. Line-tabs mode is a property of the environment. For example, the following .ds x a\t\c .ds y b\t\c .ds z c .ta 1i 3i \*x \*y \*z yields a b c whereas in line-tabs mode, the same input gives a b c instead. **.lsm **[_name_] Set the leading space macro (trap) to _name_. If there are leading space characters on an input line, _name_ is invoked in lieu of the usual _roff_ behavior; the leading spaces are removed. The count of leading spaces on an input line is stored in **\n[lsn]**, and the amount of corresponding horizontal motion in **\n[lss]**, irrespective of whether a leading space trap is set. When it is, the leading spaces are removed from the input line, and no motion is produced before calling _name_. If no argument is supplied, the default leading space behavior is (re-)established. **.mso _**file_ As “**so**”, except that _file_ is sought in the same directories as arguments to the [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) and [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) **-m **command-line option are (the “tmac path”). If the file name to be interpolated has the form _name_**.tmac **and it isn't found, **mso **tries to include **tmac._**name_ instead and vice versa. If _file_ does not exist, a warning in category “**file**” is emitted and the request has no other effect. **.msoquiet _**file_ As **mso**, but no warning is emitted if _file_ does not exist. **.nop _**anything_ Interpret _anything_ as if it were an input line. **nop **resembles “**.if 1**”; it puts a break on the output if _anything_ is empty. Unlike “**if**”, it cannot govern conditional blocks. Its application is to maintain consistent indentation within macro defini‐ tions even when producing text lines. **.nroff **Make the **n **conditional expression evaluate true and **t **false. See **troff**. **.open _**stream_ _file_ Open _file_ for writing and associate _stream_ with it. See **write **and **close**. **.opena _**stream_ _file_ As **open**, but if _file_ exists, append to it instead of truncating it. **.output _**contents_ Emit _contents_, which are read in copy mode, to the formatter output; this is similar to **\! **used in the top-level diversion. An initial neutral double quote in _contents_ is stripped to allow the embedding of leading spaces. **.pev **Report the state of the current environment followed by that of all other environments to the standard error stream. **.pnr **Write the names and values of all currently defined registers to the standard error stream. **.psbb _**file_ Get the bounding box of a PostScript image _file_. This file must conform to Adobe's Document Structuring Conventions; the request attempts to extract the bounding box values from a **%%BoundingBox **comment. After invocation, the _x_ and _y_ coordinates (in PostScript units) of the lower left and upper right corners can be found in the regis‐ ters **\n[llx]**, **\n[lly]**, **\n[urx]**, and **\n[ury]**, respectively. If an error occurs, these four registers are set to zero. **.pso _**command_ As “**so**”, except that input comes from the standard output stream of _command_. **.ptr **Report the names and vertical positions of all page location traps to the standard er‐ ror stream. Empty slots in the list are shown as well, because they can affect the visibility of subsequently planted traps. **.pvs _**±n_ Set the post-vertical line spacing to _n_; default scaling unit is “**p**”. With no argu‐ ment, the post-vertical line space is set to its previous value. In GNU _troff_, the distance between text baselines consists of the extra pre-vertical line spacing set by the most negative **\x **argument on the pending output line, the ver‐ tical spacing (**vs**), the extra post-vertical line spacing set by the most positive **\x** argument on the pending output line, and the post-vertical line spacing set by this request. **.rchar _**c_ ... Remove definition of each ordinary or special character _c_, undoing the effect of a **char**, **fchar**, or **schar **request. Glyphs, which are defined by font description files, cannot be removed. Spaces and tabs may separate _c_ arguments. ### .return Within a macro, return immediately. If called with an argument, return twice, namely from the current macro and from the macro one level higher. No effect otherwise. **.rfschar _**f_ _c_ ... Remove each fallback special character _c_ for font _f_. Spaces and tabs may separate _c_ arguments. See **fschar**. **.rj **[_n_] Right-align the next _n_ input lines. Without an argument, right-align the next input line. **rj **implies “**.ce 0**”, and **ce **implies “**.rj 0**”. **.rnn _**r1_ _r2_ Rename register _r1_ to _r2_. If _r1_ doesn't exist, the request is ignored. **.schar _**c_ _contents_ Define global fallback character _c_ as _contents_. See **char**; the distinction is that a character defined with **schar **is located after the list of fonts declared with the **special **request but before any mounted special fonts. **.shc **[_c_] Set the soft hyphen character, inserted when a word is hyphenated automatically or at a hyphenation character, to _c_. If _c_ is omitted, the soft hyphen character is set to the default, **\[hy]**. If the selected glyph does not exist in the font in use at a po‐ tential hyphenation point, then the line is not broken at that point. Neither charac‐ ter definitions (**char **and similar) nor translations (**tr **and similar) are considered when assigning the soft hyphen character. **.shift _**n_ In a macro, shift the arguments by _n_ positions: argument _i_ becomes argument _i_-_n_; argu‐ ments 1 to _n_ are no longer available. If _n_ is missing, arguments are shifted by 1. No effect otherwise. **.sizes _**s1_ _s2_ ... _sn_ [**0**] Set the available type sizes to _s1_, _s2_, ... _sn_ scaled points. The list of sizes can be terminated by an optional “**0**”. Each _si_ can also be a range _m_–_n_. In contrast to the device description file directive of the same name (see [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown)), the argu‐ ment list can't extend over more than one line. **.soquiet _**file_ As “**so**”, but no warning is emitted if _file_ does not exist. **.special _**f_ ... Declare each font _f_ as special, searching it for glyphs not found in the selected font. Without arguments, this list of special fonts is made empty. **.spreadwarn **[_limit_] Emit a **break **warning if the additional space inserted for each space between words in an output line adjusted to both margins with “**.ad b**” is larger than or equal to _limit_. A negative value is treated as zero; an absent argument toggles the warning on and off without changing _limit_. The default scaling unit is **m**. At startup, **spreadwarn **is in‐ active and _limit_ is 3 m. For example, “**.spreadwarn 0.2m**” causes a warning if **break **warnings are not suppressed and _troff_ must add 0.2 m or more for each inter-word space in a line. **.stringdown _**str_ **.stringup _**str_ Alter the string named _str_ by replacing each of its bytes with its lowercase (**down**) or uppercase (**up**) version (if one exists). Special characters (see [_groff_char_(7)](https://www.chedong.com/phpMan.php/man/groffchar/7/markdown)) will often transform in the expected way due to the regular naming convention for accented characters. When they do not, use substrings and/or catenation. **.ds resume R\['e]sum\['e]\"** **\*[resume]** **.stringdown resume** **\*[resume]** **.stringup resume** **\*[resume]** Résumé résumé RÉSUMÉ **.sty _**n_ _s_ Associate abstract style _s_ with font mounting position _n_. **.substring _**string_ _start_ [_end_] Replace the string named _string_ with its substring bounded by the indices _start_ and _end_, inclusively. The first character in the string has index 0. If _end_ is omitted, it is implicitly set to the largest valid value (the string length minus one). Nega‐ tive indices count backwards from the end of the string: the last character has in‐ dex -1, the character before the last has index -2, and so on. **.ds xxx abcdefgh** **.substring xxx 1 -4** **\*[xxx]** bcde **.substring xxx 2** **\*[xxx]** de **.tkf _**f_ _s1_ _n1_ _s2_ _n2_ Enable track kerning for font _f_. When the current font is _f_ the width of every glyph is increased by an amount between _n1_ and _n2_; when the current type size is less than or equal to _s1_ the width is increased by _n1_; when it is greater than or equal to _s2_ the width is increased by _n2_; when the type size is greater than or equal to _s1_ and less than or equal to _s2_ the increase in width is a linear function of the type size. **.tm1 _**message_ As **tm **request, but strips a leading neutral double quote from _message_ to allow the em‐ bedding of leading spaces. **.tmc _**message_ As **tm1 **request, but does not append a newline. **.trf _**file_ Transparently output the contents of file _file_. Each line is output as if preceded by **\!**; however, the lines are not subject to copy-mode interpretation. If the file does not end with a newline, then a newline is added. Unlike **cf**, _file_ cannot contain char‐ acters that are invalid as input to GNU _troff_. For example, you can define a macro _x_ containing the contents of file _f_, using .di x .trf f .di **.trin _**abcd_ This is the same as the **tr **request except that the **asciify **request uses the character code (if any) before the character translation. Example: .trin ax .di xxx a .br .di .xxx .trin aa .asciify xxx .xxx The result is “x a”. Using **tr**, the result would be “x x”. **.trnt _**abcd_ This is the same as the **tr **request except that the translations do not apply to text that is transparently throughput into a diversion with **\!**. For example, .tr ab .di x \!.tm a .di .x prints **b**; if **trnt **is used instead of **tr **it prints **a**. **.troff **Make the **t **conditional expression evaluate true and **n **false. See **nroff**. **.unformat _**div_ Unformat the diversion _div_. Unlike **asciify**, **unformat **handles only tabs and spaces be‐ tween words, the latter usually arising from spaces or newlines in the input. Tabs are treated as input tokens, and spaces become adjustable again. The vertical sizes of lines are not preserved, but glyph information (font, type size, space width, and so on) is retained. **.vpt _**n_ If _n_ is non-zero or missing, enable vertical position traps (the default), otherwise disable them. Vertical position traps are those set by the **ch**, **wh**, and **dt **requests. **.warn **[_n_] Select the categories, or “types”, of reported warnings. _n_ is the sum of the numeric codes associated with each warning category that is to be enabled; all other cate‐ gories are disabled. The categories and their associated codes are listed in section “Warnings” of [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). For example, “**.warn 0**” disables all warnings, and “**.warn 1**” disables all warnings except those about missing glyphs. If no argument is given, all warning categories are enabled. **.warnscale _**si_ Set the scaling unit used in warnings to _si_. Valid values for _si_ are **u**, **i **(the de‐ fault), **c**, **p**, and **P**. **.while _**cond-expr_ _anything_ Evaluate the conditional expression _cond-expr_, and repeatedly execute _anything_ unless and until _cond-expr_ evaluates false. _anything,_ which is often a conditional block, is referred to as the **while **request's _body._ _troff_ treats the body of a **while **request similarly to that of a **de **request (albeit one not read in copy mode), but stores it under an internal name and deletes it when the loop finishes. The operation of a macro containing a **while **request can slow signifi‐ cantly if the **while **body is large. Each time the macro is executed, the **while **body is parsed and stored again. An often better solution—and one that is more portable, since AT&T _troff_ lacked the **while **request—is to instead write a recursive macro. It will be parsed only once (unless you redefine it). To prevent infinite loops, the de‐ fault number of available recursion levels is 1,000 or somewhat less (because things other than macro calls can be on the input stack). You can disable this protective measure, or raise the limit, by setting the **slimit **register. See section “Debugging” below. If a **while **body begins with a conditional block, its closing brace must end an input line. The **break **and **continue **requests alter a **while **loop's flow of control. **.write _**stream_ _anything_ Write _anything_ to _stream_, which must previously have been the subject of an **open **re‐ quest, followed by a newline. _anything_ is read in copy mode. An initial neutral dou‐ ble quote in _anything_ is stripped to allow the embedding of leading spaces. **.writec _**stream_ _anything_ As **write**, but without a trailing newline. **.writem _**stream_ _name_ Write the contents of the macro or string _name_ to _stream_, which must previously have been the subject of an **open **request. _name_ is read in copy mode. ### Extended requests **.cf _**file_ In a diversion, embed an object which, when reread, will cause the contents of _file_ to be copied verbatim to the output. In AT&T _troff_, the contents of _file_ are immediately copied to the output regardless of whether a diversion is being written to; this be‐ havior is so anomalous that it must be considered a bug. **.de _**name_ [_end-name_] **.am _**name_ [_end-name_] **.ds _**name_ [_contents_] **.as _**name_ [_contents_] In compatibility mode, these requests behave similarly to **de1**, **am1**, **ds1**, and **as1**, re‐ spectively: a “compatibility save” token is inserted at the beginning, and a “compati‐ bility restore” token at the end, with compatibility mode switched on during execu‐ tion. **.hy _**n_ New values 16 and 32 are available; the former enables hyphenation before the last character in a word, and the latter enables hyphenation after the first character in a word. **.ss _**word-space-size_ [_additional-sentence-space-size_] A second argument sets the amount of additional space separating sentences on the same output line. If omitted, this amount is set to _word-space-size_. Both arguments are in twelfths of current font's space width (typically one-fourth to one-third em for Western scripts; see [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown)). The default for both parameters is 12. Negative values are erroneous. **.ta **[[_n1_ _n2_ ... _nn_ ]**T _**r1_ _r2_ ... _rn_] _groff_ supports an extended syntax to specify repeating tab stops after the “**T**” mark. These values are always taken as relative distances from the previous tab stop. This is the idiomatic way to specify tab stops at equal intervals in _groff_. The syntax summary above instructs _groff_ to set tabs at positions _n1_, _n2_, ..., _nn_, then at _nn_+_r1_, _nn_+_r2_, ..., _nn_+_rn_, then at _nn_+_rn_+_r1_, _nn_+_rn_+_r2_, ..., _nn_+_rn_+_rn_, and so on. ### New registers GNU _troff_ exposes more formatter state via many new read-only registers. Their names often correspond to the requests that affect them. **\n[.br] **Within a macro call, interpolate 1 if the macro is called with the “normal” con‐ trol character (“.” by default), and 0 otherwise. This facility allows the reli‐ able modification of requests. Using this register outside of a macro definition makes no sense. .als bp*orig bp .de bp .tm before bp .ie \\n[.br] .bp*orig .el 'bp*orig .tm after bp .. **\n[.C] **Interpolate 1 if compatibility mode is in effect, 0 otherwise. See **cp**. **\n[.cdp] **Interpolate depth of last glyph added to the environment. It is positive if the glyph extends below the baseline. **\n[.ce] **Interpolate number of input lines remaining to be centered. **\n[.cht] **Interpolate height of last glyph added to the environment. It is positive if the glyph extends above the baseline. **\n[.color] **Interpolate 1 if colors are enabled, 0 otherwise. **\n[.cp] **Within a “**do**” request, interpolate the saved value of compatibility mode (see **\n[.C] **above). **\n[.csk] **Interpolate skew of last glyph added to the environment. The _skew_ of a glyph is how far to the right of the center of a glyph the center of an accent over that glyph should be placed. **\n[.ev] **Interpolate name of current environment. This is a string-valued register. **\n[.fam] **Interpolate name of default font family. This is a string-valued register. **\n[.fn] **Interpolate resolved name of the selected font. This is a string-valued regis‐ ter. **\n[.fp] **Interpolate next free font mounting position. **\n[.g] **Interpolate 1. Test with “**if**” or **ie **to check whether GNU _troff_ is the formatter. **\n[.height] **Interpolate font height. See **\H**. **\n[.hla] **Interpolate hyphenation language of the environment. This is a string-valued register. **\n[.hlc] **Interpolate count of immediately preceding consecutive hyphenated lines in the environment. **\n[.hlm] **Interpolate maximum number of consecutive hyphenated lines allowed in the envi‐ ronment. **\n[.hy] **Interpolate hyphenation mode of the environment. **\n[.hym] **Inteprolate hyphenation margin of the environment. **\n[.hys] **Interpolate hyphenation space adjustment threshold of the environment. **\n[.in] **Interpolate indentation amount applicable to the pending output line. **\n[.int] **Interpolate 1 if the previous output line was interrupted (ended with **\c**), 0 oth‐ erwise. **\n[.kern] **Interpolate 1 if pairwise kerning is enabled, 0 otherwise. **\n[.lg] **Interpolate ligature mode. ### \n[.linetabs] Interpolate 1 if line-tabs mode is enabled, 0 otherwise. **\n[.ll] **Interpolate line length applicable to the pending output line. **\n[.lt] **Interpolate title line length. **\n[.m] **Interpolate name of the selected stroke color. This is a string-valued register. **\n[.M] **Interpolate name of the selected fill color. This is a string-valued register. **\n[.ne] **Interpolate amount of space demanded by the most recent **ne **request that caused a page location trap to be sprung. See **\n[.trunc]**. **\n[.nm] **Interpolate 1 if output line numbering is enabled (even if temporarily sup‐ pressed), 0 otherwise. **\n[.ns] **Interpolate 1 if no-space mode is enabled, 0 otherwise. **\n[.O] **Interpolate output suppression level. See **\O**. **\n[.P] **Interpolate 1 if the current page is selected for output. See **-o **command-line option to [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). **\n[.pe] **Interpolate 1 during page ejection, 0 otherwise. **\n[.pn] **Interpolate next page number (either that set by **pn**, or that of the current page plus 1). **\n[.ps] **Interpolate type size in scaled points. **\n[.psr] **Interpolate most recently requested type size in scaled points. **\n[.pvs] **Interpolate post-vertical line spacing amount. **\n[.rj] **Interpolate number of input lines remaining to be right-aligned. **\n[.slant] **Interpolate font slant. See **\S**. **\n[.sr] **Interpolate most recently requested type size in points as a decimal fraction. This is a string-valued register. ### \n[.ss] **\n[.sss] **Interpolate values of minimal inter-word space and additional inter-sentence space, respectively, in twelfths of the space width of the selected font. **\n[.sty] **Interpolate selected abstract font style, if any. This is a string-valued regis‐ ter. **\n[.tabs] **Interpolate representation of the tab stop settings in a form suitable for pas‐ sage to the **ta **request. **\n[.trunc] **Interpolate amount of vertical space truncated by the most recently sprung page location trap, or, if the trap was sprung by an **ne **request, minus the amount of vertical motion produced by the **ne **request. In other words, at the point a trap is sprung, **\n[.trunc] **represents the difference of what the vertical position would have been but for the trap, and what the vertical position actually is. See **\n[.ne]**. **\n[.U] **Interpolate 1 if in unsafe mode, 0 otherwise. See **-U **command-line option to [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). **\n[.vpt] **Interpolate 1 if vertical position traps are enabled, 0 otherwise. **\n[.warn] **Interpolate warning mode. See section “Warnings” of [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). **\n[.x] **Interpolate major version number of the running _troff_ formatter. For example, if the version number is 1.23.0, then **\n[.x] **contains 1. **\n[.y] **Interpolate minor version number of the running _troff_ formatter. For example, if the version number is 1.23.0, then **\n[.y] **contains 23. **\n[.Y] **Interpolate revision number of the running _troff_ formatter. For example, if the version number is 1.23.0, then **\n[.Y] **contains 0. **\n[.zoom] **Interpolate magnification of font, in thousandths, or 0 if magnification unused. See **fzoom**. The following (writable) registers are set by the **psbb **request. ### \n[llx] ### \n[lly] ### \n[urx] ### \n[ury] Interpolate the (upper, lower, left, right) bounding box values (in PostScript units) of the most recently processed PostScript image. The following (writable) registers are set by the **\w **escape sequence. ### \n[rst] **\n[rsb] **Like **\n[st] **and **\n[sb]**, but taking account of the heights and depths of glyphs. In other words, these registers store the highest and lowest vertical positions attained by the argument formatted by the **\w **escape sequence, doing what AT&T _troff_ documented **\n[st] **and **\n[sb] **as doing. **\n[ssc] **The amount of horizontal space (possibly negative) that should be added to the last glyph before a subscript. **\n[skw] **How far to right of the center of the last glyph in the **\w **argument, the center of an accent from a roman font should be placed over that glyph. Other writable registers are as follows. Those relating to date and time are initialized us‐ ing [_localtime_(3)](https://www.chedong.com/phpMan.php/man/localtime/3/markdown) at formatter startup. **\n[c.] **Interpolate input line number. **\n[.c] **is a read-only alias of this register. **\n[hours] **Interpolate number of hours elapsed since midnight. **\n[hp] **Interpolate horizontal position relative to that at the start of the input line. ### \n[lsn] **\n[lss] **Interpolate count of leading spaces on input line and amount of corresponding horizontal motion, respectively. **\n[minutes] **Interpolate number of minutes elapsed in the hour. **\n[seconds] **Interpolate number of seconds elapsed in the minute. **\n[systat] **Interpolate return value of [_system_(3)](https://www.chedong.com/phpMan.php/man/system/3/markdown) function executed by most recent **sy **re‐ quest. **\n[slimit] **Interpolates maximum quantity of objects on _troff_'s internal input stack (de‐ fault: 1000). If non-positive, there is no limit: recursion can continue until program memory is exhausted. **\n[year] **Interpolate Gregorian year. AT&T _troff_'s **\[yr] **interpolates the Gregorian year minus 1900. ### Miscellaneous GNU _troff_ predefines one string, **.T**, containing the argument given to the **-T **command-line op‐ tion, namely the output device (for example, **pdf **or **utf8**). The (read-only) _register_ **.T **in‐ terpolates 1 if GNU _troff_ is run with the **-T **command-line option, and 0 otherwise. A font not listed in the output device's _DESC_ file's **fonts **directive is automatically mounted at the next available font position when it is selected. If you mount a font explicitly with the **fp **request, you should do so on the first unused position, which can be found in the **.fp** register. Unparameterized string interpolation does not conceal the arguments to a macro being inter‐ preted. Thus, in a macro definition, the call of another macro with the existing argument list, **._**xx_ **\\$@** is more efficiently done with **\\*[_**xx_**]\\** (that is, with string interpolation). The trailing backslashes prevent the final newline in the macro definition from being interpolated, potentially putting an unwanted blank line on the output. See section “Punning Names” in [_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown). If a font description file contains pairwise kerning information, glyphs from that font are kerned. Kerning between two glyphs can be inhibited by placing a dummy character **\& **between them. GNU _troff_ keeps track of the nesting depth of escape sequence interpolations and other uses of delimiters, as in the **tl **request and the output comparison operator (that is, input like **'foo'bar' **as a conditional expression), so the only characters you need to avoid using as de‐ limiters are those that appear in the arguments you input, not any that result from interpo‐ lation. Typically, **' **works fine. Use visible characters as delimiters in GNU _troff_, not “ASCII” controls like BEL (Control+G). The implementation of **\$@ **ensures that the double quotes surrounding an argument appear at an interpolation depth different from that of the arguments themselves. Similarly, in bracket-form escape sequences like **\f[ZCMI], **a right bracket **] **does not end the sequence unless it occurs at the same interpolation depth as the opening **[**, so input like \f[\*[my-family]\*[my-style]] works as desired. In compatibility mode, no attention is paid to the interpolation depth. In GNU _troff_, the **tr **request can map characters to the unbreakable space escape sequence **\~** as a special case (**tr **normally operates only on _characters_). This feature replaces the odd- parity **tr **mapping trick used in AT&T _troff_ documents, where a character, often **~**, was “sacri‐ ficed” by mapping it to “nothing”, drafting it into use as an unadjustable, unbreakable space. (This feature was gratuitous even in early AT&T _troff,_ which supported the **\_**space_ es‐ cape sequence by 1976.) Often, it makes more sense to use GNU _troff_'s **\~ **escape sequence in‐ stead, which has been adopted by every other active _troff_ implementation except that of Illu‐ mos, as well as by the non_-troff_ _mandoc_. Translation of a character to **\~ **is unnecessary. GNU _troff_ permits tabs and spaces after the first dot on a control line that ends a macro de‐ finition. .if t \{\ . de bar . nop Hello, I'm 'bar'. . . .\} ## Formatter output The page description language output by GNU _troff_ is modeled after that used by AT&T _troff_ once the latter adopted a device-independent approach in the early 1980s. Only the differ‐ ences are documented here. For a fuller discussion, see [_groff_out_(5)](https://www.chedong.com/phpMan.php/man/groffout/5/markdown). Glyph and font names can be of arbitrary length; postprocessors should not assume that they are at most two characters. A glyph to be formatted is always drawn from the current font; in contrast to AT&T device-independent _troff_, drivers need not search special fonts to find a glyph. ### Units The argument to the **s **command is in scaled points (units of points/_n_, where _n_ is the argument to the **sizescale **command in the _DESC_ file). The argument to the “**x H**” command is also in scaled points. ### Simple commands If the **tcommand **directive is present in the output device's _DESC_ file, GNU _troff_ employs the following two commands. **t _**xyz_... Typeset word _xyz_; that is, set a sequence of ordinary glyphs named _x_, _y_, _z_, ..., ter‐ minated by a space or newline; an optional second integer argument is ignored (this allows the formatter to generate an even number of arguments). Each glyph is set at the current drawing position, and the position is then advanced horizontally by the glyph's width. A glyph's width is read from its metrics in the font description file, scaled to the current type size, and rounded to a multiple of the horizontal motion quantum. Use the **C **command to emplace glyphs of special characters. **u _**n_ _xyz_... Typeset word _xyz_ with track kerning. As **t**, but after placing each glyph, the drawing position is further advanced horizontally by _n_ basic units. New commands implement color support. **mc _**cyan_ _magenta_ _yellow_ **md** **mg _**gray_ **mk _**cyan_ _magenta_ _yellow_ _black_ **mr _**red_ _green_ _blue_ Set the components of the stroke color with respect to various color spaces. **md **re‐ sets the stroke color to the default value. The arguments are integers in the range 0 to 65535. A new device control subcommand is available. **x u _**n_ If _n_ is 1, start underlining of spaces. If _n_ is 0, stop underlining of spaces. This facility is needed for the **cu **request in _nroff_ mode and is ignored otherwise. ### Extended drawing commands GNU _pic_ does not produce _troff_ escape sequences employing these extensions if its **-n **option is given. **Df _**n_ Set the shade of gray used to fill geometric objects to _n_, which must be an integer. 0 corresponds to white and 1000 to black. A grayscale ramp spans the two. A value outside this range uses the stroke color as the fill color. The fill color is opaque. Normally the default is black, but some drivers may provide a way of changing this. **Df **is obsolete since 2002, superseded by **DFg **below. The corresponding **\D'f' **escape sequence should not be used: its argument is rounded to an integer multiple of the horizontal motion quantum, which can limit the precision of _n_. **DC _**d_ Draw a filled circle of diameter _d_ with its leftmost point at the drawing position. **DE _**h_ _v_ Draw a filled ellipse, of horizontal axis _h_ and vertical axis _v_, with its leftmost point at the drawing position. **Dp _**dx_1_dy_1..._dxndyn_ Draw a polygon with, for _i_=1,...,_n_+1, its _i_th vertex at the drawing position +_**j**_−=Σ**1**(_dxj_,_dyj_). _groff_ output drivers automatically close polygons, drawing a line from (_dxn_,_dyn_) back to (_dx_1,_dy_1). The drawing position is left at the last _specified_ ver‐ tex, but this may change in a future version of GNU _troff_. Heirloom Doctools _troff_, like DWB _troff_, by default does not close the polygon. In its _groff_ compatibility mode, Heirloom closes the polygon but leaves the drawing position _unchanged_—that is, at the polygon's _initial_ drawing position. At the moment, GNU _pic_ uses this command only to generate triangles and rectangles. **DP _**dx_1_dy_1..._dxndyn_ As **Dp**, but draw a filled rather than a stroked polygon. **Dt _**n_ Set the line thickness to _n_ basic units. AT&T _troff_ output drivers use a thickness proportional to the type size; this is the GNU _troff_ default. A negative _n_ requests this explicitly. An _n_ of zero selects the smallest available line thickness. A difficulty arises in how the drawing position should be changed after the execution of these commands. This has little importance to most users, since the output of GNU _grn_ and _pic_ does not depend on it. Given a drawing command of the form **D_**z_ _x_1_y_1..._xnyn_, where _z_ is not **c **or **e**, AT&T _troff_ treats each _xi_ as a horizontal motion, each _yi_ as a vertical one, and therefore assumes that the width of the drawn object is _in_=Σ1_xi_, and its height is _in_=Σ1_yi_. (Verify its assumption about height by examining the **st **and **sb **registers after using such a drawing command in a **\w **escape sequence). For the sake of compatibility, GNU _troff_ also fol‐ lows this rule, even though it frustrates extensions to the **D **command that set drawing para‐ meters rather than rendering objects, producing ugly results in the case of **Dt **and **Df**, or otherwise don't parameterize objects as a series of vertices, as with GNU _troff_'s filled el‐ lipse, **DE**. Thus after executing a **D **command of the form **D_**z_ _x_1_y_1..._xnyn_, the drawing position should be increased by (_in_=Σ1_xi_,_in_=Σ1_yi_). In a future release, GNU _troff_ and its output drivers may abandon the application of this assumption to drawing commands not explicitly specified in the AT&T “Troff User's Manual”. Fill color selection is implemented with another set of extensions. **DFc _**cyan_ _magenta_ _yellow_ ### DFd **DFg _**gray_ **DFk _**cyan_ _magenta_ _yellow_ _black_ **DFr _**red_ _green_ _blue_ Set the components of the fill color as described under the **\M **escape sequence above. **DFd **restores the device's default fill color. The drawing position is not updated, in contrast to **Df**. ### Device control syntax extension GNU _troff_ introduces a line continuation convention, permitting the argument to the **x X **com‐ mand to contain newlines. A newline in the input is transformed to the sequence “_newline_**+**”. When interpreting an **x X **command, a postprocessor should therefore be prepared for a plus sign after a newline; if it occurs, preserve the newline, discard the plus sign, and continue to collect the input into the argument of the **x X **command. A newline _not_ followed by a plus sign terminates the **x X **command. An application of this feature is the embedding of Post‐ Script or PDF language command streams into _troff_ output. GNU _troff_ guarantees that the first three output commands it emits are as follows. x T _device_ x res _n_ _h_ _v_ x init ## Debugging In addition to AT&T _troff_'s debugging features, GNU _troff_ emits more error diagnostics when syntactical or semantic nonsense is encountered and supports several warning categories; the output of these can be selected with **warn**. Also see the **-E**, **-w**, and **-W **options of [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). Backtraces can be automatically produced when errors or warnings occur (the **-b **option of [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)) or generated on demand (**backtrace**). _groff_ also adds more flexible diagnostic output requests (**tmc **and **tm1**). More aspects of for‐ matter state can be examined with requests that write lists of defined registers (**pnr**), envi‐ ronments (**pev**), and page location traps (**ptr**) to the standard error stream. ## Implementation differences GNU _troff_'s features sometimes cause incompatibilities with documents written assuming old implementations of _troff_. Some GNU extensions to _troff_ are supported by other implementa‐ tions. When adjusting to both margins, AT&T _troff_ at first adjusts spaces starting from the right; GNU _troff_ begins from the left. Both implementations adjust spaces from opposite ends on al‐ ternating output lines to prevent “rivers” in the text. GNU _troff_ does not always hyphenate words as AT&T _troff_ does. The AT&T implementation uses a set of hard-coded rules specific to U.S. English, while GNU _troff_ uses language-specific hy‐ phenation pattern files derived from TeX. In some versions of _troff_ there was limited space to store hyphenation exceptions (arguments to the **hw **request); GNU _troff_ has no such restric‐ tion. Long names may be GNU _troff_'s most obvious innovation. AT&T _troff_ interprets “**.dsabcd**” as defining a string “**ab**” with contents “**cd**”. Normally, GNU _troff_ interprets this as a call of a macro named “**dsabcd**”. AT&T _troff_ also interprets **\*[ **and **\n[ **as an interpolation of a string or register, respectively, called “**[**”. In GNU _troff_, however, the “**[**” is normally in‐ terpreted as beginning the enclosure of a long identifier. In compatibility mode, GNU _troff_ interprets names in the traditional way, which means that they are limited to one or two characters. See the **-C **option in [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) and, above, the **.C **and **.cp **registers, and **cp **and “**do**” requests, for more on compatibility mode. The register **\n[.cp] **is specialized and may require a statement of rationale. When writing macro packages or documents that use GNU _troff_ features and which may be mixed with other packages or documents that do not—common scenarios include serial processing of man pages or use of the “**so**” or **mso **requests—you may desire correct operation regardless of compatibility mode enablement in the surrounding context. It may occur to you to save the existing value of **\n(.C **into a register, say, **_C**, at the beginning of your file, turn compatibility mode off with “**.cp 0**”, then restore it from that register at the end with “**.cp \n(_C**”. At the same time, a modular design of a document or macro package may lead you to multiple layers of in‐ clusion. You cannot use the same register name everywhere lest you “clobber” the value from a preceding or enclosing context. The two-character register name space of AT&T _troff_ is confining and mnemonically challenging; you may wish to use GNU _troff_'s more capacious name space. However, attempting “**.nr _my_saved_C \n(.C**” will not work in compatibility mode; the register name is too long. “This is exactly what **.do **is for,” you think, “**.do nr _my_saved_C** **\n(.C**”. The foregoing will always save zero to your register, because “**do**” turns compatibil‐ ity mode _off_ while it interprets its argument list. What you need is: .do nr _my_saved_C \n[.cp] .cp 0 at the beginning of your file, followed by .cp \n[_my_saved_C] .do rr _my_saved_C at the end. As in the C language, we all have to share one big name space, so choose a reg‐ ister name that is unlikely to collide with other uses. The existence of the **.T **string is a common feature of post-CSTR #54 _troff_s—DWB 3.3, Solaris, Heirloom Doctools, and Plan 9 _troff_ all support it—but valid values are specific to each im‐ plementation. The behavior of the **.T **register in GNU _troff_ differs from AT&T _troff_, which interpolated 1 only if _nroff_ was the formatter and was called with **-T**. The **lf **request sets the number of the _current_ input line in AT&T _troff_, and the _next_ in GNU _troff_. AT&T _troff_ had only environments named “**0**”, “**1**”, and “**2**”. In GNU _troff_, any number of envi‐ ronments may exist, using any valid identifiers for their names. GNU _troff_ normally tracks the interpolation depth of escape sequence parameters and other de‐ limited structures, but not in compatibility mode. See section “Miscellaneous” above. In compatibility mode, the escape sequences **\f**, **\H**, **\m**, **\M**, **\R**, **\s**, and **\S **are transparent at the beginning of an input line for the purpose of recognizing a control character, because they modify formatter state (**\R**) or properties of the environment (the rest) and therefore do not create output nodes. For example, this code produces bold output in both cases, but the text differs, .de xx ' Hello! .. \fB.xx\fP formatting “.xx” normally and “Hello!” in compatibility mode. GNU _troff_ request names unrecognized by other _troff_ implementations will likely be ignored; escape sequences that are GNU _troff_ extensions are liable to format their function selector character. For example, the adjustable, non-breaking space escape sequence **\~ **is also sup‐ ported by Heirloom Doctools _troff_ 050915 (September 2005), _mandoc_ 1.9.5 (2009-09-21), _neatroff_ (commit 1c6ab0f6e, 2016-09-13), and Plan 9 from User Space _troff_ (commit 93f8143600, 2022-08-12), but not by Solaris/Illumos _troff_s, which will render it as **~**. GNU _troff_ does not allow the use of the escape sequences **\|**, **\^**, **\&**, **\{**, **\}**, **\_**space_, **\'**, **\`**, **\-**, **\_**, **\!**, **\%**, or **\c **in identifiers; AT&T _troff_ does. The **\A **escape sequence (see subsec‐ tion “Escape sequences” above) may be helpful in avoiding their use. Normally, the syntax form **\s_**n_ accepts only a single character (a digit) for _n_, consistently with other forms that originated in AT&T _troff_, like **\***, **\$**, **\f**, **\g**, **\k**, **\n**, and **\z**. In com‐ patibility mode only, a non-zero _n_ must be in the range 4–39. Legacy documents relying upon this quirk of parsing should be migrated to another **\s **form. [Background: The Graphic Sys‐ tems C/A/T phototypesetter (the original device target for AT&T _troff_) supported only a few discrete type sizes in the range 6–36 points, so Ossanna contrived a special case in the parser to do what the user must have meant. Kernighan warned of this in the 1992 revision of CSTR #54 (§2.3), and more recently, McIlroy referred to it as a “living fossil”.] Fractional type sizes cause one noteworthy incompatibility. In AT&T _troff_ the **ps **request ig‐ nores scaling units and thus “**.ps 10u**” sets the type size to 10 points, whereas in GNU _troff_ it sets the type size to 10 _scaled_ points, which may be a much smaller measurement. See sub‐ section “Fractional type sizes and new scaling units” above. The **ab **request differs from AT&T _troff_: GNU _troff_ writes no message to the standard error stream if no arguments are given, and it exits with a failure status instead of a successful one. The **bp **request differs from AT&T _troff_: GNU _troff_ does not accept a scaling unit on the argu‐ ment, a page number; the former (somewhat uselessly) does. In AT&T _troff_ the **pm **request reports macro, string, and diversion sizes in units of 128-byte blocks, and an argument reduces the report to a sum of the above in the same units. GNU _troff_ ignores any arguments and reports the sizes in bytes. Unlike AT&T _troff_, GNU _troff_ does not ignore the **ss **request if the output is a terminal de‐ vice; instead, the values of minimum inter-word and additional inter-sentence space are each rounded down to the nearest multiple of 12. In GNU _troff_ there is a fundamental difference between (unformatted) characters and (format‐ ted) glyphs. Everything that affects how a glyph is output is stored with the glyph node; once a glyph node has been constructed, it is unaffected by any subsequent requests that are executed, including **bd**, **cs**, **tkf**, **tr**, or **fp **requests. Normally, glyphs are constructed from characters immediately before the glyph is added to an output line. Macros, diversions, and strings are all, in fact, the same type of object; they contain a sequence of intermixed character and glyph nodes. Special characters transform from one to the other: before being added to the output, they behave as characters; afterward, they are glyphs. A glyph node does not behave like a character node when it is processed by a macro: it does not inherit any of the special properties that the character from which it was constructed might have had. For example, the input .di x \\\\ .br .di .x produces “**\\**” in GNU _troff_. Each pair of backslashes becomes one backslash _glyph;_ the re‐ sulting backslashes are thus not interpreted as escape _characters_ when they are reread as the diversion is output. AT&T _troff_ _would_ interpret them as escape characters when rereading them and end up printing one “**\**”. One way to format a backslash in most documents is with the **\e **escape sequence; this formats the glyph of the current escape character, regardless of whether it is used in a diversion; it also works in both GNU _troff_ and AT&T _troff_. (Naturally, if you've changed the escape character, you need to prefix the “**e**” with whatever it is—and you'll likely get something other than a backslash in the output.) The other correct way, appropriate in contexts independent of the backslash's common use as a _roff_ escape character—perhaps in discussion of character sets or other programming languages— is the character escape **\(rs **or **\[rs]**, for “reverse solidus”, from its name in the ECMA-6 (ISO/IEC 646) standard. [This escape sequence is not portable to AT&T _troff_, but is to its lineal descendant, Heirloom Doctools _troff_, as of its 060716 release (July 2006).] To store an escape sequence in a diversion that is interpreted when the diversion is reread, either use the traditional **\! **transparent output facility, or, if this is unsuitable, the new **\? **escape sequence. See subsection “Escape sequences” above and sections “Diversions” and “gtroff Internals” in _Groff:_ _The_ _GNU_ _Implementation_ _of_ _troff_, the _groff_ Texinfo manual. In the somewhat pathological case where a diversion exists containing a partially collected line and a partially collected line at the top-level diversion has never existed, AT&T _troff_ will output the partially collected line at the end of input; GNU _troff_ will not. ### Formatter output incompatibilities Its extensions notwithstanding, the _groff_ intermediate output format has some incompatibili‐ ties with that of AT&T _troff_, but better compatibility is sought; problem reports and patches are welcome. The following incompatibilities are known. • The drawing position after rendering polygons is inconsistent with AT&T _troff_ practice. Other implementations have diverged on this point as well. • The output cannot be easily rescaled to other devices as AT&T _troff_'s could. ## Authors This document was written by [James Clark](mailto:), [Werner Lemberg](mailto:), [Bernd Warken](mailto:), and G. Branden Robin‐ son. **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 output 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, provides additional insights into the device and font description file formats and output format. [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown), [_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown), [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) groff 1.23.0 31 March 2024 [_groff_diff_(7)](https://www.chedong.com/phpMan.php/man/groffdiff/7/markdown)