1groff(7) Miscellaneous Information Manual groff(7)
2
6 groff - GNU roff language reference
7
9 groff is short for GNU roff, a free reimplementation of the AT&T de‐
10 vice-independent troff typesetting system. See roff(7) for a survey of
11 and background on roff systems.
12 This document is intended as a reference. The primary groff manual,
14 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
15 Lemberg, is a better resource for learners, containing many examples
16 and much discussion. It is written in Texinfo; you can browse it in‐
17 teractively with “info groff”. Additional formats, including plain
18 text, HTML, DVI, and PDF, may be available in /usr/share/doc/groff.
19 groff is also a name for an extended dialect of the roff language. We
21 use “roff” to denote features that are universal, or nearly so, among
22 implementations of this family. We apply the term “groff” to the lan‐
23 guage documented here, the GNU implementation of the overall system,
24 the project that develops that system, and the command of that name.
25 GNU troff, installed on this system as troff(1), is the formatter: a
27 program that reads device and font descriptions (groff_font(5)), inter‐
28 prets the groff language expressed in text input files, and translates
29 that input into a device-independent output format (groff_out(5)) that
30 is usually then post-processed by an output driver to produce Post‐
31 Script, PDF, HTML, DVI, or terminal output.
32
34 Input to GNU troff is organized into lines separated by the Unix new‐
35 line character (U+000A), and must be in one of two character encodings
36 it can recognize: IBM code page 1047 on EBCDIC systems, and ISO Latin-1
37 (8859-1) otherwise. Use of ISO 646-1991:IRV (“US-ASCII”) or (equiva‐
38 lently) the “Basic Latin” subset of ISO 10646 (“Unicode”) is recom‐
39 mended; see groff_char(7). The preconv(1) preprocessor transforms
40 other encodings, including UTF-8, to satisfy troff's requirements.
41
43 Several input characters are syntactically significant to groff.
44 . A dot at the beginning of an input line marks it as a control line.
46 It can also follow the .el and .nop requests, and the condition in
47 .if, .ie, and .while requests. The control character invokes re‐
48 quests and calls macros by the name that follows it. The .cc re‐
49 quest can change the control character.
50 ' The neutral apostrophe is the no-break control character, recog‐
52 nized where the control character is. It suppresses the (first)
53 break implied by the .bp, .cf, .fi, .fl, .in, .nf, .rj, .sp, .ti,
54 and .trf requests. The requested operation takes effect at the
55 next break. It makes .br nilpotent. The no-break control charac‐
56 ter can be changed with the .c2 request. When formatted, “'” may
57 be typeset as a typographical quotation mark; use the \[aq] special
58 character escape sequence to format a neutral apostrophe glyph.
59 " The neutral double quote can be used to enclose arguments to macros
61 and strings, and is required if those arguments contain space or
62 tab characters. In the .ds, .ds1, .as, and .as1 requests, an ini‐
63 tial neutral double quote in the second argument is stripped off to
64 allow embedding of leading spaces. To include a double quote in‐
65 side a quoted argument, use the \[dq] special character escape se‐
66 quence (which also serves to typeset the glyph in text).
67 \ A backslash introduces an escape sequence. The escape character
69 can be changed with the .ec request; .eo disables escape sequence
70 recognition. Use the \[rs] special character escape sequence to
71 format a backslash glyph, and \e to typeset the glyph of the cur‐
72 rent escape character.
73 ( An opening parenthesis is special only in certain escape sequences;
75 when recognized, it introduces an argument of exactly two charac‐
76 ters. groff offers the more flexible square bracket syntax.
77 [ An opening bracket is special only in certain escape sequences;
79 when recognized, it introduces an argument (list) of any length,
80 not including a closing bracket.
81 ] A closing bracket is special only when an escape sequence using an
83 opening bracket as an argument delimiter is being interpreted. It
84 ends the argument (list).
85 Additionally, the Control+A character (U+0001) in text is interpreted
87 as a leader (see below).
88 Horizontal white space characters are significant to groff, but trail‐
90 ing spaces on text lines are ignored.
91 space Space characters separate arguments in request invocations,
93 macro calls, and string interpolations. In text, they separate
94 words. Multiple adjacent space characters in text cause groff
95 to attempt end-of-sentence detection on the preceding word (and
96 trailing punctuation). The amount of space between words and
97 sentences is controlled by the .ss request. When filling is
98 enabled (the default), a line may be broken at a space. When
99 adjustment is enabled (the default), inter-word spaces are ex‐
100 panded until the output line reaches the configured length. An
101 adjustable but non-breaking space is available with \~. To get
102 a space of fixed width, use one of the escape sequences ‘\ ’
103 (the escape character followed by a space), \0, \|, \^, or \h;
104 see section “Escape sequences” below.
105 newline In text, a newline puts an inter-word space onto the output
107 and, if filling is enabled, triggers end-of-sentence recogni‐
108 tion on the preceding text. See section “Line continuation”
109 below.
110 tab A tab character in text causes the drawing position to advance
112 to the next defined tab stop.
113
115 The formatter interprets input horizontal tab characters (“tabs”) and
116 Control+A characters (“leaders”) into movements to the next tab stop.
117 Tabs simply move to the next tab stop; leaders place enough periods to
118 fill the space. Tab stops are by default located every half inch mea‐
119 sured from the drawing position corresponding to the beginning of the
120 input line; see section “Page geometry” of roff(7). Tabs and leaders
121 do not cause breaks and therefore do not interrupt filling. Tab stops
122 can be configured with the ta request, and tab and leader glyphs with
123 the tc and lc requests, respectively.
124
126 When filling is enabled, input and output line breaks generally do not
127 correspond. The roff language therefore distinguishes input and output
128 line continuation.
129 A backslash \ immediately followed by a newline, sometimes discussed as
131 \newline, suppresses the effects of that newline on the input. The
132 next input line thus retains the classification of its predecessor as a
133 control or text line. \newline is useful for managing line lengths in
134 the input during document maintenance; you can break an input line in
135 the middle of a request invocation, macro call, or escape sequence.
136 Input line continuation is invisible to the formatter, with two excep‐
137 tions: the | operator recognizes the new input line, and the input line
138 counter register .c is incremented.
139 The \c escape sequence continues an output line. Nothing on the input
141 line after it is formatted. In contrast to \newline, a line after \c
142 is treated as a new input line, so a control character is recognized at
143 its beginning. The visual results depend on whether filling is en‐
144 abled. An intervening control line that causes a break overrides \c,
145 flushing out the pending output line in the usual way. The register
146 .int contains a positive value if the last output line was continued
147 with \c; this datum is associated with the environment.
148
150 groff supports color output with a variety of color spaces and up to 16
151 bits per channel. Some devices, particularly terminals, may be more
152 limited. When color support is enabled, two colors are current at any
153 given time: the stroke color, with which glyphs, rules (lines), and
154 geometric objects like circles and polygons are drawn, and the fill
155 color, which can be used to paint the interior of a closed geometric
156 figure. The color, defcolor, gcolor, and fcolor requests; \m and \M
157 escape sequences; and .color, .m, and .M registers exercise color sup‐
158 port.
159 Each output device has a color named “default”, which cannot be rede‐
161 fined. A device's default stroke and fill colors are not necessarily
162 the same. For the dvi, html, pdf, ps, and xhtml output devices, troff
163 automatically loads a macro file defining many color names at startup.
164 By the same mechanism, the devices supported by grotty(1) recognize the
165 eight standard ISO 6429/ECMA-48 color names (also known vulgarly as
166 “ANSI colors”).
167
169 Numeric parameters that specify measurements are expressed as integers
170 or decimal fractions with an optional scaling unit suffixed. A scaling
171 unit is a letter that immediately follows the last digit of a number.
172 Digits after the decimal point are optional.
173 Measurements are scaled by the scaling unit and stored internally (with
175 any fractional part discarded) in basic units. The device resolution
176 can therefore be obtained by storing a value of “1i” to a register.
177 The only constraint on the basic unit is that it is at least as small
178 as any other unit.
179 u Basic unit.
181 i Inch; defined as 2.54 centimeters.
182 c Centimeter.
183 p Point; a typesetter's unit used for measuring type size. There
184 are 72 points to an inch.
185 P Pica; another typesetter's unit. There are 6 picas to an inch
186 and 12 points to a pica.
187 s, z Scaled points and multiplication by the output device's
188 sizescale parameter, respectively.
189 f Multiplication by 65,536; scales decimal fractions in the inter‐
190 val [0, 1] to 16-bit unsigned integers.
191 The magnitudes of other scaling units depend on the text formatting pa‐
193 rameters in effect.
194 m Em; an em is equal to the current type size in points.
196 n En; an en is one-half em.
197 v Vee; distance between text baselines.
198 M Hundredth of an em.
199 Motion quanta
201 An output device's basic unit u is not necessarily its smallest ad‐
202 dressable length; u can be smaller to avoid problems with integer
203 roundoff. The minimum distances that a device can work with in the
204 horizontal and vertical directions are termed its motion quanta, stored
205 in the .H and .V registers, respectively. Measurements are rounded to
206 applicable motion quanta. Half-quantum fractions round toward zero.
207 Default units
209 A general-purpose register (one created or updated with the nr request;
210 see section “Registers” below) is implicitly dimensionless, or reckoned
211 in basic units if interpreted in a measurement context. But it is con‐
212 venient for many requests and escape sequences to infer a scaling unit
213 for an argument if none is specified. An explicit scaling unit (not
214 after a closing parenthesis) can override an undesirable default. Ef‐
215 fectively, the default unit is suffixed to the expression if a scaling
216 unit is not already present. GNU troff's use of integer arithmetic
217 should also be kept in mind; see below.
218
220 A numeric expression evaluates to an integer. The following operators
221 are recognized.
222 + addition
224 - subtraction
225 * multiplication
226 / truncating division
227 % modulus
228 ────────────────────────────────────────────
229 unary + assertion, motion, incrementation
230 unary - negation, motion, decrementation
231 ────────────────────────────────────────────
232 ; scaling
233 >? maximum
234 <? minimum
235 ────────────────────────────────────────────
236 < less than
237 > greater than
238 <= less than or equal
239 >= greater than or equal
240 = equal
241 == equal
242 ────────────────────────────────────────────
243 & logical conjunction (“and”)
244 : logical disjunction (“or”)
245 ! logical complementation (“not”)
246 ────────────────────────────────────────────
247 ( ) precedence
248 ────────────────────────────────────────────
249 | boundary-relative motion
250 troff provides a set of mathematical and logical operators familiar to
252 programmers—as well as some unusual ones—but supports only integer
253 arithmetic. (Provision is made for interpreting and reporting decimal
254 fractions in certain cases.) The internal data type used for computing
255 results is usually a 32-bit signed integer, which suffices to represent
256 magnitudes within a range of ±2 billion. (If that's not enough, see
257 groff_tmac(5) for the 62bit.tmac macro package.)
258 Arithmetic infix operators perform a function on the numeric expres‐
260 sions to their left and right; they are + (addition), - (subtraction),
261 * (multiplication), / (truncating division), and % (modulus). Truncat‐
262 ing division rounds to the integer nearer to zero, no matter how large
263 the fractional portion. Overflow and division (or modulus) by zero are
264 errors and abort evaluation of a numeric expression.
265 Arithmetic unary operators operate on the numeric expression to their
267 right; they are - (negation) and + (assertion—for completeness; it does
268 nothing). The unary minus must often be used with parentheses to avoid
269 confusion with the decrementation operator, discussed below.
270 The sign of the modulus of operands of mixed signs is determined by the
272 sign of the first. Division and modulus operators satisfy the follow‐
273 ing property: given a dividend a and a divisor b, a quotient q formed
274 by “(a / b)” and a remainder r by “(a % b)”, then qb + r = a.
275 GNU troff's scaling operator, used with parentheses as (c;e), evaluates
277 a numeric expression e using c as the default scaling unit. If c is
278 omitted, scaling units are ignored in the evaluation of e. GNU troff
279 also provides a pair of operators to compute the extrema of two oper‐
280 ands: >? (maximum) and <? (minimum).
281 Comparison operators comprise < (less than), > (greater than), <= (less
283 than or equal), >= (greater than or equal), and = (equal). == is a
284 synonym for =. When evaluated, a comparison is replaced with “0” if it
285 is false and “1” if true. In the roff language, positive values are
286 true, others false.
287 We can operate on truth values with the logical operators & (logical
289 conjunction or “and”) and : (logical disjunction or “or”). They evalu‐
290 ate as comparison operators do. A logical complementation (“not”) op‐
291 erator, !, works only within “if”, “ie”, and “while” requests. Fur‐
292 thermore, ! is recognized only at the beginning of a numeric expression
293 not contained by another numeric expression. In other words, it must
294 be the “outermost” operator. Including it elsewhere in the expression
295 produces a warning in the “number” category (see troff(1)), and its ex‐
296 pression evaluates false. This unfortunate limitation maintains com‐
297 patibility with AT&T troff. Test a numeric expression for falsity by
298 comparing it to a false value.
299 The roff language has no operator precedence: expressions are evaluated
301 strictly from left to right, in contrast to schoolhouse arithmetic.
302 Use parentheses ( ) to impose a desired precedence upon subexpressions.
303 For many requests and escape sequences that cause motion on the page,
305 the unary operators + and - work differently when leading a numeric ex‐
306 pression. They then indicate a motion relative to the drawing posi‐
307 tion: positive is down in vertical contexts, right in horizontal ones.
308 + and - are also treated differently by the following requests and es‐
310 cape sequences: bp, in, ll, pl, pn, po, ps, pvs, rt, ti, \H, \R, and
311 \s. Here, leading plus and minus signs serve as incrementation and
312 decrementation operators, respectively. To negate an expression, sub‐
313 tract it from zero or include the unary minus in parentheses with its
314 argument.
315 A leading | operator indicates a motion relative not to the drawing po‐
317 sition but to a boundary. For horizontal motions, the measurement
318 specifies a distance relative to a drawing position corresponding to
319 the beginning of the input line. By default, tab stops reckon move‐
320 ments in this way. Most escape sequences do not; | tells them to do
321 so. For vertical motions, the | operator specifies a distance from the
322 first text baseline on the page or in the current diversion, using the
323 current vertical spacing.
324 The \B escape sequence tests its argument for validity as a numeric ex‐
326 pression.
327 A register interpolated as an operand in a numeric expression must have
329 an Arabic format; luckily, this is the default.
330 Due to the way arguments are parsed, spaces are not allowed in numeric
332 expressions unless the (sub)expression containing them is surrounded by
333 parentheses.
334
336 An identifier labels a GNU troff datum such as a register, name (macro,
337 string, or diversion), typeface, color, special character, character
338 class, environment, or stream. Valid identifiers consist of one or
339 more ordinary characters. An ordinary character is an input character
340 that is not the escape character, a leader, tab, newline, or invalid as
341 GNU troff input.
342 Invalid input characters are subset of control characters (from the
344 sets “C0 Controls” and “C1 Controls” as Unicode describes them). When
345 troff encounters one in an identifier, it produces a warning in cate‐
346 gory “input” (see section “Warnings” in troff(1)). They are removed
347 during interpretation: an identifier “foo”, followed by an invalid
348 character and then “bar”, is processed as “foobar”.
349 On a machine using the ISO 646, 8859, or 10646 character encodings, in‐
351 valid input characters are 0x00, 0x08, 0x0B, 0x0D–0x1F, and 0x80–0x9F.
352 On an EBCDIC host, they are 0x00–0x01, 0x08, 0x09, 0x0B, 0x0D–0x14,
353 0x17–0x1F, and 0x30–0x3F. Some of these code points are used by troff
354 internally, making it non-trivial to extend the program to accept UTF-8
355 or other encodings that use characters from these ranges.
356 An identifier with a closing bracket (“]”) in its name can't be ac‐
358 cessed with bracket-form escape sequences that expect an identifier as
359 a parameter. Similarly, the identifier “(” can't be interpolated ex‐
360 cept with bracket forms.
361 If you begin a macro, string, or diversion name with either of the
363 characters “[” or “]”, you foreclose use of the refer(1) preprocessor,
364 which recognizes “.[” and “.]” as bibliographic reference delimiters.
365 The escape sequence \A tests its argument for validity as an identi‐
367 fier.
368 How GNU troff handles the interpretation of an undefined identifier de‐
370 pends on the context. There is no way to invoke an undefined request;
371 such syntax is interpreted as a macro call instead. If the identifier
372 is interpreted as a string, macro, or diversion, troff emits a warning
373 in category “mac”, defines it as empty, and interpolates nothing. If
374 the identifier is interpreted as a register, troff emits a warning in
375 category “reg”, initializes it to zero, and interpolates that value.
376 See section “Warnings” in troff(1), and subsection “Interpolating reg‐
377 isters” and section “Strings” below. Attempting to use an undefined
378 typeface, style, special character, color, character class, environ‐
379 ment, or stream generally provokes an error diagnostic.
380 Identifiers for requests, macros, strings, and diversions share one
382 name space; special characters and character classes another. No other
383 object types do.
384
386 Control characters are recognized only at the beginning of an input
387 line, or at the beginning of the branch of a control structure request;
388 see section “Control structures” below.
389 A few requests cause a break implicitly; use the no-break control char‐
391 acter to prevent the break. Break suppression is its sole behavioral
392 distinction. Employing the no-break control character to invoke re‐
393 quests that don't cause breaks is harmless but poor style.
394 The control character “.” and the no-break control character “'” can be
396 changed with the cc and c2 requests, respectively. Within a macro def‐
397 inition, register .br indicates the control character used to call it.
398
400 A control character is optionally followed by tabs and/or spaces and
401 then an identifier naming a request or macro. The invocation of an un‐
402 recognized request is interpreted as a macro call. Defining a macro
403 with the same name as a request replaces the request. Deleting a re‐
404 quest name with the rm request makes it unavailable. The als request
405 can alias requests, permitting them to be wrapped or non-destructively
406 replaced. See section “Strings” below.
407 There is no inherent limit on argument length or quantity. Most re‐
409 quests take one or more arguments, and ignore any they do not expect.
410 A request may be separated from its arguments by tabs or spaces, but
411 only spaces can separate an argument from its successor. Only one be‐
412 tween arguments is necessary; any excess is ignored. GNU troff does
413 not allow tabs for argument separation.
414 Generally, a space within a request argument is not relevant, not mean‐
416 ingful, or is supported by bespoke provisions, as with the tl request's
417 delimiters. Some requests, like ds, interpret the remainder of the
418 control line as a single argument. See section “Strings” below.
419 Spaces and tabs immediately after a control character are ignored.
421 Commonly, authors structure the source of documents or macro files with
422 them.
423
425 If a macro of the desired name does not exist when called, it is cre‐
426 ated, assigned an empty definition, and a warning in category “mac” is
427 emitted. Calling an undefined macro does end a macro definition naming
428 it as its end macro (see section “Writing macros” below).
429 To embed spaces within a macro argument, enclose the argument in neu‐
431 tral double quotes ‘"’. Horizontal motion escape sequences are some‐
432 times a better choice for arguments to be formatted as text.
433 The foregoing raises the question of how to embed neutral double quotes
435 or backslashes in macro arguments when those characters are desired as
436 literals. In GNU troff, the special character escape sequence \[rs]
437 produces a backslash and \[dq] a neutral double quote.
438 In GNU troff's AT&T compatibility mode, these characters remain avail‐
440 able as \(rs and \(dq, respectively. AT&T troff did not consistently
441 define these special characters, but its descendants can be made to
442 support them. See groff_font(5). If even that is not feasible, see
443 the “Calling Macros” section of the groff Texinfo manual for the com‐
444 plex macro argument quoting rules of AT&T troff.
445
447 Whereas requests must occur on control lines, escape sequences can oc‐
448 cur intermixed with text and may appear in arguments to requests,
449 macros, and other escape sequences. An escape sequence is introduced
450 by the escape character, a backslash \. The next character selects the
451 escape's function.
452 Escape sequences vary in length. Some take an argument, and of those,
454 some have different syntactical forms for a one-character, two-charac‐
455 ter, or arbitrary-length argument. Others accept only an arbitrary-
456 length argument. In the former scheme, a one-character argument fol‐
457 lows the function character immediately, an opening parenthesis “(” in‐
458 troduces a two-character argument (no closing parenthesis is used), and
459 an argument of arbitrary length is enclosed in brackets “[]”. In the
460 latter scheme, the user selects a delimiter character. A few escape
461 sequences are idiosyncratic, and support both of the foregoing conven‐
462 tions (\s), designate their own termination sequence (\?), consume in‐
463 put until the next newline (\!, \", \#), or support an additional modi‐
464 fier character (\s again, and \n).
465 If an escape character is followed by a character that does not iden‐
467 tify a defined operation, the escape character is ignored (producing a
468 diagnostic of the “escape” warning category, which is not enabled by
469 default) and the following character is processed normally.
470 Escape sequence interpolation is of higher precedence than escape se‐
472 quence argument interpretation. This rule affords flexibility in using
473 escape sequences to construct parameters to other escape sequences.
474 The escape character can be interpolated (\e). Requests permit the es‐
476 cape mechanism to be deactivated (eo) and restored, or the escape char‐
477 acter changed (ec), and to save and restore it (ecs and ecr).
478
480 Some escape sequences that require parameters use delimiters. The neu‐
481 tral apostrophe ' is a popular choice and shown in this document. The
482 neutral double quote " is also commonly seen. Letters, numerals, and
483 leaders can be used. Punctuation characters are likely better choices,
484 except for those defined as infix operators in numeric expressions; see
485 below.
486 The following escape sequences don't take arguments and thus are al‐
488 lowed as delimiters: \space, \%, \|, \^, \{, \}, \', \`, \-, \_, \!,
489 \?, \), \/, \,, \&, \:, \~, \0, \a, \c, \d, \e, \E, \p, \r, \t, and \u.
490 However, using them this way is discouraged; they can make the input
491 confusing to read.
492 A few escape sequences, \A, \b, \o, \w, \X, and \Z, accept a newline as
494 a delimiter. Newlines that serve as delimiters continue to be recog‐
495 nized as input line terminators. Use of newlines as delimiters in es‐
496 cape sequences is also discouraged.
497 Finally, the escape sequences \D, \h, \H, \l, \L, \N, \R, \s, \S, \v,
499 and \x prohibit many delimiters.
500 • the numerals 0–9 and the decimal point “.”
502 • the (single-character) operators +-/*%<>=&:()
504 • any escape sequences other than \%, \:, \{, \}, \', \`, \-,
506 \_, \!, \/, \c, \e, and \p
507 Delimiter syntax is complex and flexible primarily for historical rea‐
509 sons; the foregoing restrictions need be kept in mind mainly when using
510 groff in AT&T compatibility mode. GNU troff keeps track of the nesting
511 depth of escape sequence interpolations, so the only characters you
512 need to avoid using as delimiters are those that appear in the argu‐
513 ments you input, not any that result from interpolation. Typically, '
514 works fine. See section “Implementation differences” in groff_diff(7).
515
517 As discussed in roff(7), the first character on an input line is
518 treated specially. Further, formatting a glyph has many consequences
519 on formatter state (see section “Environments” below). Occasionally,
520 we want to escape this context or embrace some of those consequences
521 without actually rendering a glyph to the output. \& interpolates a
522 dummy character, which is constitutive of output but invisible. Its
523 presence alters the interpretation context of a subsequent input char‐
524 acter, and enjoys several applications: preventing the insertion of ex‐
525 tra space after an end-of-sentence character, preventing interpretation
526 of a control character at the beginning of an input line, preventing
527 kerning between two glyphs, and permitting the tr request to remap a
528 character to “nothing”. \) works as \& does, except that it does not
529 cancel a pending end-of-sentence state.
530
532 groff has “if” and “while” control structures like other languages.
533 However, the syntax for grouping multiple input lines in the branches
534 or bodies of these structures is unusual.
535 They have a common form: the request name is (except for .el “else”)
537 followed by a conditional expression cond-expr; the remainder of the
538 line, anything, is interpreted as if it were an input line. Any quan‐
539 tity of spaces between arguments to requests serves only to separate
540 them; leading spaces in anything are therefore not seen. anything ef‐
541 fectively cannot be omitted; if cond-expr is true and anything is
542 empty, the newline at the end of the control line is interpreted as a
543 blank line (and therefore a blank text line).
544 It is frequently desirable for a control structure to govern more than
546 one request, macro call, or text line, or a combination of the forego‐
547 ing. The opening and closing brace escape sequences \{ and \} perform
548 such grouping. Brace escape sequences outside of control structures
549 have no meaning and produce no output.
550 \{ should appear (after optional spaces and tabs) immediately subse‐
552 quent to the request's conditional expression. \} should appear on a
553 line with other occurrences of itself as necessary to match \{ se‐
554 quences. It can be preceded by a control character, spaces, and tabs.
555 Input after any quantity of \} sequences on the same line is processed
556 only if all the preceding conditions to which they correspond are true.
557 Furthermore, a \} closing the body of a .while request must be the last
558 such escape sequence on an input line.
559 Conditional expressions
561 The .if, .ie, and .while requests test the truth values of numeric ex‐
562 pressions. They also support several additional Boolean operators; the
563 members of this expanded class are termed conditional expressions;
564 their truth values are as shown below.
565 cond-expr... ...is true if...
567 ────────────────────────────────────────────────────────────────────────
568 's1's2' s1 produces the same formatted output as s2.
569 c g a glyph g is available.
570 d m a string, macro, diversion, or request m is defined.
571 e the current page number is even.
572 F f a font named f is available.
573 m c a color named c is defined.
574 n the formatter is in nroff mode.
575 o the current page number is odd.
576 r n a register named n is defined.
577 S s a font style named s is available.
578 t the formatter is in troff mode.
579 v n/a (historical artifact; always false).
580 If the first argument to an .if, .ie, or .while request begins with a
582 non-alphanumeric character apart from ! (see below); it performs an
583 output comparison test. Shown first in the table above, the output
584 comparison operator interpolates a true value if formatting its compar‐
585 ands s1 and s2 produces the same output commands. Other delimiters can
586 be used in place of the neutral apostrophes. troff formats s1 and s2
587 in separate environments; after the comparison, the resulting data are
588 discarded. The resulting glyph properties, including font family,
589 style, size, and slant, must match, but not necessarily the requests
590 and/or escape sequences used to obtain them. Motions must match in
591 orientation and magnitude to within the applicable horizontal or verti‐
592 cal motion quantum of the device, after rounding.
593 Surround the comparands with \? to avoid formatting them; this causes
595 them to be compared character by character, as with string comparisons
596 in other programming languages. Since comparands protected with \? are
597 read in copy mode, they need not even be valid groff syntax. The es‐
598 cape character is still lexically recognized, however, and consumes the
599 next character.
600 The above operators can't be combined with most others, but a leading
602 “!”, not followed immediately by spaces or tabs, complements an expres‐
603 sion. Spaces and tabs are optional immediately after the “c”, “d”,
604 “F”, “m”, “r”, and “S” operators, but right after “!”, they end the
605 predicate and the conditional evaluates true. (This bizarre behavior
606 maintains compatibility with AT&T troff.)
607
609 In the following request and escape sequence specifications, most argu‐
610 ment names were chosen to be descriptive. A few denotations may re‐
611 quire introduction.
612 c denotes a single input character.
614 font a font either specified as a font name or a numeric
615 mounting position.
616 anything all characters up to the end of the line, to the end‐
617 ing delimiter for the escape sequence, or within \{
618 and \}. Escape sequences may generally be used freely
619 in anything, except when it is read in copy mode.
620 message is a character sequence to be emitted on the standard
621 error stream. Special character escape sequences are
622 not interpreted.
623 n is a numeric expression that evaluates to a non-nega‐
624 tive integer.
625 npl is a numeric expression constituting a count of subse‐
626 quent productive input lines; that is, those that di‐
627 rectly produce formatted output. Text lines produce
628 output, as do control lines containing requests like
629 .tl or escape sequences like \D. Macro calls are not
630 themselves productive, but their interpolated contents
631 can be.
632 ±N is a numeric expression with a meaning dependent on
633 its sign.
634 If a numeric expression presented as ±N starts with a ‘+’ sign, an in‐
636 crement in the amount of of N is applied to the value applicable to the
637 request or escape sequence. If it starts with a ‘-’ sign, a decrement
638 of magnitude N is applied instead. Without a sign, N replaces any ex‐
639 isting value. A leading minus sign in N is always interpreted as a
640 decrementation operator, not an algebraic sign. To assign a register a
641 negative value or the negated value of another register, enclose it
642 with its operand in parentheses or subtract it from zero. If a prior
643 value does not exist (the register was undefined), an increment or
644 decrement is applied as if to 0.
645
647 Not all details of request behavior are outlined here. See the groff
648 Texinfo manual or, for features new to GNU troff, groff_diff(7).
649 .ab Abort processing; exit with failure status.
651 .ab message
652 Abort processing; write message to the standard error stream
653 and exit with failure status.
654 .ad Enable output line alignment and adjustment using the mode
655 stored in \n[.j].
656 .ad c Enable output line alignment and adjustment in mode c
657 (c=b,c,l,n,r). Sets \n[.j].
658 .af register c
659 Assign format c to register, where c is “i”, “I”, “a”, “A”,
660 or a sequence of decimal digits whose quantity denotes the
661 minimum width in digits to be used when the register is in‐
662 terpolated. “i” and “a” indicate Roman numerals and basic
663 Latin alphabetics, respectively, in the lettercase specified.
664 The default is 0.
665 .aln new old
666 Create alias (additional name) new for existing register
667 named old.
668 .als new old
669 Create alias (additional name) new for existing request,
670 string, macro, or diversion old.
671 .am macro Append to macro until .. is encountered.
672 .am macro end
673 Append to macro until .end is called.
674 .am1 macro
675 Same as .am but with compatibility mode switched off during
676 macro expansion.
677 .am1 macro end
678 Same as .am but with compatibility mode switched off during
679 macro expansion.
680 .ami macro
681 Append to a macro whose name is contained in the string macro
682 until .. is encountered.
683 .ami macro end
684 Append to a macro indirectly. macro and end are strings
685 whose contents are interpolated for the macro name and the
686 end macro, respectively.
687 .ami1 macro
688 Same as .ami but with compatibility mode switched off during
689 macro expansion.
690 .ami1 macro end
691 Same as .ami but with compatibility mode switched off during
692 macro expansion.
693 .as name Create string name with empty contents; no operation if name
694 already exists.
695 .as name contents
696 Append contents to string name.
697 .as1 string
698 .as1 string contents
699 As .as, but with compatibility mode disabled when contents
700 interpolated.
701 .asciify diversion
702 Unformat ASCII characters, spaces, and some escape sequences
703 in diversion.
704 .backtrace
705 Write the state of the input stack to the standard error
706 stream. See the -b option of groff(1).
707 .bd font Stop emboldening font font.
708 .bd font n
709 Embolden font by overstriking its glyphs offset by n-1 units.
710 See register .b.
711 .bd special-font font
712 Stop emboldening special-font when font is selected.
713 .bd special-font font n
714 Embolden special-font, overstriking its glyphs offset by n-1
715 units when font is selected. See register .b.
716 .blm Unset blank line macro (trap). Restore default handling of
717 blank lines.
718 .blm name Set blank line macro (trap) to name.
719 .box Stop directing output to current diversion; any pending out‐
720 put line is discarded.
721 .box name Direct output to diversion name, omitting a partially col‐
722 lected line.
723 .boxa Stop appending output to current diversion; any pending out‐
724 put line is discarded.
725 .boxa name
726 Append output to diversion name, omitting a partially col‐
727 lected line.
728 .bp Break page and start a new one.
729 .bp ±N Break page, starting a new one numbered ±N.
730 .br Break output line.
731 .brp Break output line; adjust if applicable.
732 .break Break out of a while loop.
733 .c2 Reset no-break control character to “'”.
734 .c2 o Recognize ordinary character o as no-break control character.
735 .cc Reset control character to ‘.’.
736 .cc o Recognize ordinary character o as the control character.
737 .ce Break, center the output of the next productive input line
738 without filling, and break again.
739 .ce npl Break, center the output of the next npl productive input
740 lines without filling, then break again. If npl ≤ 0, stop
741 centering.
742 .cf file Copy contents of file without formatting to the (top-level)
743 diversion.
744 .cflags n c1 c2 ...
745 Assign properties encoded by n to characters c1, c2, and so
746 on.
747 .ch name Unplant page location trap name.
748 .ch name vpos
749 Change page location trap name planted by .wh by moving its
750 location to vpos (default scaling unit v).
751 .char c contents
752 Define ordinary or special character c as contents.
753 .chop object
754 Remove the last character from the macro, string, or diver‐
755 sion named object.
756 .class name c1 c2 ...
757 Define a (character) class name comprising the characters or
758 range expressions c1, c2, and so on.
759 .close stream
760 Close the stream.
761 .color Enable output of color-related device-independent output com‐
762 mands.
763 .color n If n is zero, disable output of color-related device-indepen‐
764 dent output commands; otherwise, enable them.
765 .composite from to
766 Map glyph name from to glyph name to while constructing a
767 composite glyph name.
768 .continue Finish the current iteration of a while loop.
769 .cp Enable compatibility mode.
770 .cp n If n is zero, disable compatibility mode, otherwise enable
771 it.
772 .cs font n m
773 Set constant character width mode for font to n/36 ems with
774 em m.
775 .cu Continuously underline the output of the next productive in‐
776 put line.
777 .cu npl Continuously underline the output of the next npl productive
778 input lines. If npl=0, stop continuously underlining.
779 .da Stop appending output to current diversion.
780 .da name Append output to diversion name.
781 .de macro Define or redefine macro until “..” occurs at the start of a
782 control line in the current conditional block.
783 .de macro end
784 Define or redefine macro until end is invoked or called at
785 the start of a control line in the current conditional block.
786 .de1 macro
787 As .de, but disable compatibility mode during macro expan‐
788 sion.
789 .de1 macro end
790 As “.de macro end”, but disable compatibility mode during
791 macro expansion.
792 .defcolor ident scheme color-component ...
793 Define a color named ident. scheme identifies a color space
794 and determines the number of required color-components; it
795 must be one of “rgb” (three components), “cmy” (three),
796 “cmyk” (four), or “gray” (one). “grey” is accepted as a syn‐
797 onym of “gray”. The color components can be encoded as a
798 single hexadecimal value starting with # or ##. The former
799 indicates that each component is in the range 0–255 (0–FF),
800 the latter the range 0–65,535 (0–FFFF). Alternatively, each
801 color component can be specified as a decimal fraction in the
802 range 0–1, interpreted using a default scaling unit of “f”,
803 which multiplies its value by 65,536 (but clamps it at
804 65,535). Each output device has a color named “default”,
805 which cannot be redefined. A device's default stroke and
806 fill colors are not necessarily the same.
807 .dei macro
808 Define macro indirectly. As .de, but use interpolation of
809 string macro as the name of the defined macro.
810 .dei macro end
811 Define macro indirectly. As .de, but use interpolations of
812 strings macro and end as the names of the defined and end
813 macros.
814 .dei1 macro
815 As .dei, but disable compatibility mode during macro expan‐
816 sion.
817 .dei1 macro end
818 As .dei macro end, but disable compatibility mode during
819 macro expansion.
820 .device anything
821 Write anything, read in copy mode, to troff output as a de‐
822 vice control command. An initial neutral double quote is
823 stripped to allow embedding of leading spaces.
824 .devicem name
825 Write contents of macro or string name to troff output as a
826 device control command.
827 .di Stop directing output to current diversion.
828 .di name Direct output to diversion name.
829 .do name ...
830 Interpret the string, request, diversion, or macro name
831 (along with any arguments) with compatibility mode disabled.
832 Compatibility mode is restored (only if it was active) when
833 the expansion of name is interpreted.
834 .ds name Create empty string name.
835 .ds name contents
836 Create a string name containing contents.
837 .ds1 name
838 .ds1 name contents
839 As .ds, but with compatibility mode disabled when contents
840 interpolated.
841 .dt Clear diversion trap.
842 .dt vertical-position name
843 Set the diversion trap to macro name at vertical-position
844 (default scaling unit v).
845 .ec Recognize \ as the escape character.
846 .ec o Recognize ordinary character o as the escape character.
847 .ecr Restore escape character saved with .ecs.
848 .ecs Save the escape character.
849 .el anything
850 Interpret anything as if it were an input line if the condi‐
851 tional expression of the corresponding .ie request was false.
852 .em name Call macro name after the end of input.
853 .eo Disable the escape mechanism in interpretation mode.
854 .ev Pop environment stack, returning to previous one.
855 .ev env Push current environment onto stack and switch to env.
856 .evc env Copy environment env to the current one.
857 .ex Exit with successful status.
858 .fam Set default font family to previous value.
859 .fam name Set default font family to name.
860 .fc Disable field mechanism.
861 .fc a Set field delimiter to a and pad glyph to space.
862 .fc a b Set field delimiter to a and pad glyph to b.
863 .fchar c contents
864 Define fallback character (or glyph) c as contents.
865 .fcolor Restore previous fill color.
866 .fcolor c Set fill color to c.
867 .fi Enable filling of output lines; a pending output line is bro‐
868 ken. Sets \n[.u].
869 .fl Flush output buffer.
870 .fp pos id
871 Mount font with font description file name id at non-negative
872 position n.
873 .fp pos id font-description-file-name
874 Mount font with font-description-file-name as name id at non-
875 negative position n.
876 .fschar f c anything
877 Define fallback character (or glyph) c for font f as string
878 anything.
879 .fspecial font
880 Reset list of special fonts for font to be empty.
881 .fspecial font s1 s2 ...
882 When the current font is font, then the fonts s1, s2, ... are
883 special.
884 .ft
885 .ft P Select previous font mounting position (abstract style or
886 font); same as \f[] or \fP.
887 .ft font Select typeface font, which can be a mounting position, ab‐
888 stract style, or font name; same as \f[font] escape sequence.
889 font cannot be P.
890 .ftr font1 font2
891 Translate font1 to font2.
892 .fzoom font
893 .fzoom font 0
894 Stop magnifying font.
895 .fzoom font z
896 Set zoom factor for font to z (in thousandths; default:
897 1000).
898 .gcolor Restore previous stroke color.
899 .gcolor c Set stroke color to c.
900 .hc Reset the hyphenation character to \% (the default).
901 .hc char Change the hyphenation character to char.
902 .hcode c1 code1 [c2 code2] ...
903 Set the hyphenation code of character c1 to code1, that of c2
904 to code2, and so on.
905 .hla lang Set the hyphenation language to lang.
906 .hlm n Set the maximum quantity of consecutive hyphenated lines to
907 n.
908 .hpf pattern-file
909 Read hyphenation patterns from pattern-file.
910 .hpfa pattern-file
911 Append hyphenation patterns from pattern-file.
912 .hpfcode a b [c d] ...
913 Define mappings for character codes in hyphenation pattern
914 files read with .hpf and .hpfa.
915 .hw word ...
916 Define hyphenation overrides for each word; a hyphen “-” in‐
917 dicates a hyphenation point.
918 .hy Set automatic hyphenation mode to 1.
919 .hy 0 Disable automatic hyphenation; same as .nh.
920 .hy mode Set automatic hyphenation mode to mode; see section “Hyphena‐
921 tion” below.
922 .hym Set the (right) hyphenation margin to 0 (the default).
923 .hym length
924 Set the (right) hyphenation margin to length (default scaling
925 unit m).
926 .hys Set the hyphenation space to 0 (the default).
927 .hys hyphenation-space
928 Suppress automatic hyphenation in adjustment modes “b” or “n”
929 if the line can be justified with the addition of up to hy‐
930 phenation-space to each inter-word space (default scaling
931 unit m).
932 .ie cond-expr anything
933 If cond-expr is true, interpret anything as if it were an in‐
934 put line, otherwise skip to a corresponding .el request.
935 .if cond-expr anything
936 If cond-expr is true, then interpret anything as if it were
937 an input line.
938 .ig Ignore input (except for side effects of \R on auto-incre‐
939 menting registers) until “..” occurs at the start of a con‐
940 trol line in the current conditional block.
941 .ig end Ignore input (except for side effects of \R on auto-incre‐
942 menting registers) until .end is called at the start of a
943 control line in the current conditional block.
944 .in Set indentation amount to previous value.
945 .in ±N Set indentation to ±N (default scaling unit m).
946 .it Cancel any pending input line trap.
947 .it npl name
948 Set (or replace) an input line trap in the environment, call‐
949 ing macro name, after the next npl productive input lines
950 have been read. Lines interrupted with the \c escape se‐
951 quence are counted separately.
952 .itc Cancel any pending input line trap.
953 .itc npl name
954 As .it, except that input lines interrupted with the \c es‐
955 cape sequence are not counted.
956 .kern Enable pairwise kerning.
957 .kern n If n is zero, disable pairwise kerning, otherwise enable it.
958 .lc Unset leader repetition character.
959 .lc c Set leader repetition character to c (default: “.”).
960 .length reg anything
961 Compute the number of characters of anything and store the
962 count in the register reg.
963 .linetabs Enable line-tabs mode (calculate tab positions relative to
964 beginning of output line).
965 .linetabs 0
966 Disable line-tabs mode.
967 .lf n Set number of next input line to n.
968 .lf n file
969 Set number of next input line to n and input file name to
970 file.
971 .lg m Set ligature mode to m (0 = disable, 1 = enable, 2 = enable
972 for two-letter ligatures only).
973 .ll Set line length to previous value. Does not affect a pending
974 output line.
975 .ll ±N Set line length to ±N (default length 6.5i, default scaling
976 unit m). Does not affect a pending output line.
977 .lsm Unset the leading space macro (trap). Restore default han‐
978 dling of lines with leading spaces.
979 .lsm name Set the leading space macro (trap) to name.
980 .ls Change to the previous value of additional intra-line skip.
981 .ls n Set additional intra-line skip value to n, i.e., n-1 blank
982 lines are inserted after each text output line.
983 .lt Set length of title lines to previous value.
984 .lt ±N Set length of title lines (default length 6.5i, default scal‐
985 ing unit m).
986 .mc Cease writing margin character.
987 .mc c Begin writing margin character c to the right of each output
988 line.
989 .mc c d Begin writing margin character c on each output line at dis‐
990 tance d to the right of the right margin (default distance
991 10p, default scaling unit m).
992 .mk Mark vertical drawing position in an internal register; see
993 .rt.
994 .mk register
995 Mark vertical drawing position in register.
996 .mso file As .so, except that file is sought in the tmac directories.
997 .msoquiet file
998 As .mso, but no warning is emitted if file does not exist.
999 .na Disable output line adjustment.
1000 .ne Break page if distance to next page location trap is less
1001 than one vee.
1002 .ne d Break page if distance to next page location trap is less
1003 than distance d (default scaling unit v).
1004 .nf Disable filling of output lines; a pending output line is
1005 broken. Clears \n[.u].
1006 .nh Disable automatic hyphenation; same as “.hy 0”.
1007 .nm Deactivate output line numbering.
1008 .nm ±N
1009 .nm ±N m
1010 .nm ±N m s
1011 .nm ±N m s i
1012 Activate output line numbering: number the next output line
1013 ±N, writing numbers every m lines, with s numeral widths (\0)
1014 between the line number and the output (default 1), and in‐
1015 denting the line number by i numeral widths (default 0).
1016 .nn Suppress numbering of the next output line to be numbered
1017 with nm.
1018 .nn n Suppress numbering of the next n output lines to be numbered
1019 with nm. If n=0, cancel suppression.
1020 .nop anything
1021 Interpret anything as if it were an input line.
1022 .nr reg ±N
1023 Define or update register reg with value N.
1024 .nr reg ±N I
1025 Define or update register reg with value N and auto-increment
1026 I.
1027 .nroff Make the conditional expressions n true and t false.
1028 .ns Enable no-space mode, ignoring .sp requests until a glyph or
1029 \D primitive is output. See .rs.
1030 .nx Immediately jump to end of current file.
1031 .nx file Stop formatting current file and begin reading file.
1032 .open stream file
1033 Open file for writing and associate the stream named stream
1034 with it. Unsafe request; disabled by default.
1035 .opena stream file
1036 As .open, but append to file. Unsafe request; disabled by
1037 default.
1038 .os Output vertical distance that was saved by the .sv request.
1039 .output contents
1040 Emit contents directly to intermediate output, allowing lead‐
1041 ing whitespace if string starts with " (which is stripped
1042 off).
1043 .pc Reset page number character to ‘%’.
1044 .pc c Page number character.
1045 .pev Report the state of the current environment followed by that
1046 of all other environments to the standard error stream.
1047 .pi program
1048 Pipe output to program (nroff only). Unsafe request; dis‐
1049 abled by default.
1050 .pl Set page length to default 11i. The current page length is
1051 stored in register .p.
1052 .pl ±N Change page length to ±N (default scaling unit v).
1053 .pm Report, to the standard error stream, the names and sizes in
1054 bytes of defined macros, strings, and diversions.
1055 .pn ±N Next page number N.
1056 .pnr Write the names and contents of all defined registers to the
1057 standard error stream.
1058 .po Change to previous page offset. The current page offset is
1059 available in register .o.
1060 .po ±N Page offset N.
1061 .ps Return to previous type size.
1062 .ps ±N Set/increase/decrease the type size to/by N scaled points (a
1063 non-positive resulting type size is set to 1 u); also see
1064 \s[±N].
1065 .psbb file
1066 Retrieve the bounding box of the PostScript image found in
1067 file, which must conform to Adobe's Document Structuring Con‐
1068 ventions (DSC). See registers llx, lly, urx, ury.
1069 .pso command-line
1070 Execute command-line with popen(3) and interpolate its out‐
1071 put. Unsafe request; disabled by default.
1072 .ptr Report names and positions of all page location traps to the
1073 standard error stream.
1074 .pvs Change to previous post-vertical line spacing.
1075 .pvs ±N Change post-vertical line spacing according to ±N (default
1076 scaling unit p).
1077 .rchar c1 c2 ...
1078 Remove definition of each ordinary or special character c1,
1079 c2, ... defined by a .char, .fchar, or .schar request.
1080 .rd prompt
1081 Read insertion.
1082 .return Return from a macro.
1083 .return anything
1084 Return twice, namely from the macro at the current level and
1085 from the macro one level higher.
1086 .rfschar f c1 c2 ...
1087 Remove the font-specific definitions of glyphs c1, c2, ...
1088 for font f.
1089 .rj npl Break, right-align the output of the next productive input
1090 line without filling, then break again.
1091 .rj npl Break, right-align the output of the next npl productive in‐
1092 put lines without filling, then break again. If npl ≤ 0,
1093 stop right-aligning.
1094 .rm name Remove request, macro, diversion, or string name.
1095 .rn old new
1096 Rename request, macro, diversion, or string old to new.
1097 .rnn reg1 reg2
1098 Rename register reg1 to reg2.
1099 .rr ident Remove register ident.
1100 .rs Restore spacing; disable no-space mode. See .ns.
1101 .rt Return (upward only) to vertical position marked by .mk on
1102 the current page.
1103 .rt N Return (upward only) to vertical position N (default scaling
1104 unit v).
1105 .schar c contents
1106 Define global fallback character (or glyph) c as contents.
1107 .shc Reset the soft hyphen character to \[hy].
1108 .shc c Set the soft hyphen character to c.
1109 .shift n In a macro definition, left-shift arguments by n positions.
1110 .sizes s1 s2 ... sn [0]
1111 Set available type sizes similarly to the sizes directive in
1112 a DESC file. Each si is interpreted in units of scaled
1113 points (z).
1114 .so file Replace the request's control line with the contents of file,
1115 “sourcing” it.
1116 .soquiet file
1117 As .so, but no warning is emitted if file does not exist.
1118 .sp Break and move the next text baseline down by one vee, or un‐
1119 til springing a page location trap.
1120 .sp dist Break and move the next text baseline down by dist, or until
1121 springing a page location trap (default scaling unit v). A
1122 negative dist will not reduce the position of the text base‐
1123 line below zero. Prefixing dist with the | operator moves to
1124 a position relative to the page top for positive N, and the
1125 bottom if N is negative; in all cases, one line height (vee)
1126 is added to dist. dist is ignored inside a diversion.
1127 .special Reset global list of special fonts to be empty.
1128 .special s1 s2 ...
1129 Fonts s1, s2, etc. are special and are searched for glyphs
1130 not in the current font.
1131 .spreadwarn
1132 Toggle the spread warning on and off (the default) without
1133 changing its value.
1134 .spreadwarn N
1135 Emit a break warning if the additional space inserted for
1136 each space between words in an adjusted output line is
1137 greater than or equal to N. A negative N is treated as 0.
1138 The default scaling unit is m. At startup, .spreadwarn is
1139 inactive and N is 3 m.
1140 .ss n Set minimal inter-word spacing to n 12ths of current font's
1141 space width.
1142 .ss n m As “.ss n”, and set additional inter-sentence space to
1143 m 12ths of current font's space width.
1144 .stringdown stringvar
1145 Replace each byte in the string named stringvar with its low‐
1146 ercase version.
1147 .stringup stringvar
1148 Replace each byte in the string named stringvar with its up‐
1149 percase version.
1150 .sty n style
1151 Associate abstract style with font position n.
1152 .substring str start [end]
1153 Replace the string named str with its substring bounded by
1154 the indices start and end, inclusive. Negative indices count
1155 backwards from the end of the string.
1156 .sv As .ne, but save 1 v for output with .os request.
1157 .sv d As .ne, but save distance d for later output with .os request
1158 (default scaling unit v).
1159 .sy command-line
1160 Execute command-line with system(3). Unsafe request; dis‐
1161 abled by default.
1162 .ta n1 n2 ... nn T r1 r2 ... rn
1163 Set tabs at positions n1, n2, ..., nn, then set tabs at
1164 nn+m×rn+r1 through nn+m×rn+rn, where m increments from 0, 1,
1165 2, ... to the output line length. Each n argument can be
1166 prefixed with a “+” to place the tab stop ni at a distance
1167 relative to the previous, n(i-1). Each argument ni or ri can
1168 be suffixed with a letter to align text within the tab column
1169 bounded by tab stops i and i+1; “L” for left-aligned (the de‐
1170 fault), “C” for centered, and “R” for right-aligned.
1171 .tag
1172 .taga Reserved for internal use.
1173 .tc Unset tab repetition character.
1174 .tc c Set tab repetition character to c (default: none).
1175 .ti ±N Temporarily indent next output line (default scaling unit m).
1176 .tkf font s1 n1 s2 n2
1177 Enable track kerning for font.
1178 .tl 'left'center'right'
1179 Format three-part title.
1180 .tm message
1181 Write message, followed by a newline, to the standard error
1182 stream.
1183 .tm1 message
1184 As .tm, but an initial neutral double quote in message is re‐
1185 moved, allowing it to contain leading spaces.
1186 .tmc message
1187 As .tm1, without emitting a newline.
1188 .tr abcd...
1189 Translate ordinary or special characters a to b, c to d, and
1190 so on prior to output.
1191 .trf file Transparently output the contents of file. Unlike .cf, in‐
1192 valid input characters in file are rejected.
1193 .trin abcd...
1194 As .tr, except that .asciify ignores the translation when a
1195 diversion is interpolated.
1196 .trnt abcd...
1197 As .tr, except that translations are suppressed in the argu‐
1198 ment to \!.
1199 .troff Make the conditional expressions t true and n false.
1200 .uf font Set underline font used by .ul to font.
1201 .ul Underline (italicize in troff mode) the output of the next
1202 productive input line.
1203 .ul npl Underline (italicize in troff mode) the output of the next
1204 npl productive input line. If npl=0, stop underlining.
1205 .unformat diversion
1206 Unformat space characters and tabs in diversion, preserving
1207 font information.
1208 .vpt Enable vertical position traps.
1209 .vpt 0 Disable vertical position traps.
1210 .vs Change to previous vertical spacing.
1211 .vs ±N Set vertical spacing to ±N (default scaling unit p).
1212 .warn Enable all warning categories.
1213 .warn 0 Disable all warning categories.
1214 .warn n Enable warnings in categories whose codes sum to n; see
1215 troff(1).
1216 .warnscale su
1217 Set scaling unit used in certain warnings to su (one of u, i,
1218 c, p, or P; default: i).
1219 .wh vpos Remove visible page location trap at vpos (default scaling
1220 unit v).
1221 .wh vpos name
1222 Plant macro name as page location trap at vpos (default scal‐
1223 ing unit v), removing any visible trap already there.
1224 .while cond-expr anything
1225 Repeatedly execute anything unless and until cond-expr evalu‐
1226 ates false.
1227 .write stream anything
1228 Write anything to the stream named stream.
1229 .writec stream anything
1230 Similar to .write without emitting a final newline.
1231 .writem stream xx
1232 Write contents of macro or string xx to the stream named
1233 stream.
1234
1236 The escape sequences \", \#, \$, \*, \?, \a, \e, \n, \t, \g, \V, and
1237 \newline are interpreted even in copy mode.
1238 \" Comment. Everything up to the end of the line is ignored.
1240 \# Comment. Everything up to and including the next newline is ig‐
1241 nored.
1242 \*s Interpolate string with one-character name s.
1243 \*(st Interpolate string with two-character name st.
1244 \*[string]
1245 Interpolate string with name string (of arbitrary length).
1246 \*[string arg ...]
1247 Interpolate string with name string (of arbitrary length), tak‐
1248 ing arg ... as arguments.
1249 \$0 Interpolate name by which currently executing macro was invoked.
1250 \$n Interpolate macro or string parameter numbered n (1≤n≤9).
1251 \$(nn Interpolate macro or string parameter numbered nn (01≤nn≤99).
1252 \$[nnn]
1253 Interpolate macro or string parameter numbered nnn (nnn≥1).
1254 \$* Interpolate concatenation of all macro or string parameters,
1255 separated by spaces.
1256 \$@ Interpolate concatenation of all macro or string parameters,
1257 with each surrounded by double quotes and separated by spaces.
1258 \$^ Interpolate concatenation of all macro or string parameters as
1259 if they were arguments to the .ds request.
1260 \' is a synonym for \[aa], the acute accent special character.
1261 \` is a synonym for \[ga], the grave accent special character.
1262 \- is a synonym for \[-], the minus sign special character.
1263 \_ is a synonym for \[ul], the underrule special character.
1264 \% Control hyphenation.
1265 \! Transparent line. The remainder of the input line is inter‐
1266 preted (1) when the current diversion is read; or (2) if in the
1267 top-level diversion, by the postprocessor (if any).
1268 \?anything\?
1269 Transparently embed anything, read in copy mode, in a diversion,
1270 or unformatted as an output comparand in a conditional expres‐
1271 sion.
1272 \space Move right one word space.
1273 \~ Insert an unbreakable, adjustable space.
1274 \0 Move right by the width of a numeral in the current font.
1275 \| Move one-sixth em to the right on typesetters.
1276 \^ Move one-twelfth em to the right on typesetters.
1277 \& Interpolate a dummy character.
1278 \) Interpolate a dummy character that is transparent to end-of-sen‐
1279 tence recognition.
1280 \/ Apply italic correction. Use between an immediately adjacent
1281 oblique glyph on the left and an upright glyph on the right.
1282 \, Apply left italic correction. Use between an immediately adja‐
1283 cent upright glyph on the left and an oblique glyph on the
1284 right.
1285 \: Non-printing break point (similar to \%, but never produces a
1286 hyphen glyph).
1287 \newline
1288 Continue current input line on the next.
1289 \{ Begin conditional input.
1290 \} End conditional input.
1291 \(gl Interpolate glyph with two-character name gl.
1292 \[glyph]
1293 Interpolate glyph with name glyph (of arbitrary length).
1294 \[base-char comp ...]
1295 Interpolate composite glyph constructed from base-char and each
1296 component comp.
1297 \[charnnn]
1298 Interpolate glyph of eight-bit encoded character nnn, where
1299 0≤nnn≤255.
1300 \[unnnn[n[n]]]
1301 Interpolate glyph of Unicode character with code point
1302 nnnn[n[n]] in uppercase hexadecimal.
1303 \[ubase-char[_combining-component]...]
1304 Interpolate composite glyph from Unicode character base-char and
1305 combining-components.
1306 \a Interpolate a leader in copy mode.
1307 \A'anything'
1308 Interpolate 1 if anything is a valid identifier, and 0 other‐
1309 wise.
1310 \b'string'
1311 Build bracket: pile a sequence of glyphs corresponding to each
1312 character in string vertically, and center it vertically on the
1313 output line.
1314 \B'anything'
1315 Interpolate 1 if anything is a valid numeric expression, and 0
1316 otherwise.
1317 \c Continue output line at next input line.
1318 \C'glyph'
1319 As \[glyph], but compatible with other troff implementations.
1320 \d Move downward ½ em on typesetters.
1321 \D'drawing-command'
1322 See subsection “Drawing commands” below.
1323 \e Interpolate the escape character.
1324 \E As \e, but not interpreted in copy mode.
1325 \fP Select previous font mounting position (abstract style or font);
1326 same as “.ft” or “.ft P”.
1327 \fF Select font mounting position, abstract style, or font with one-
1328 character name or one-digit position F. F cannot be P.
1329 \f(ft Select font mounting position, abstract style, or font with two-
1330 character name or two-digit position ft.
1331 \f[font]
1332 Select font mounting position, abstract style, or font with ar‐
1333 bitrarily long name or position font. font cannot be P.
1334 \f[] Select previous font mounting position (abstract style or font).
1335 \Ff Set default font family to that with one-character name f.
1336 \F(fm Set default font family to that with two-character name fm.
1337 \F[fam]
1338 Set default font family to that with arbitrarily long name fam.
1339 \F[] Set default font family to previous value.
1340 \gr Interpolate format of register with one-character name r.
1341 \g(rg Interpolate format of register with two-character name rg.
1342 \g[reg]
1343 Interpolate format of register with arbitrarily long name reg.
1344 \h'N' Horizontally move the drawing position by N ems (or specified
1345 units); | may be used. Positive motion is rightward.
1346 \H'N' Set height of current font to N scaled points (or specified
1347 units).
1348 \kr Mark horizontal position in one-character register name r.
1349 \k(rg Mark horizontal position in two-character register name rg.
1350 \k[reg]
1351 Mark horizontal position in register with arbitrarily long
1352 name reg.
1353 \l'N[c]'
1354 Draw horizontal line of length N with character c (default:
1355 \[ru]; default scaling unit m).
1356 \L'N[c]'
1357 Draw vertical line of length N with character c (default: \[br];
1358 default scaling unit v).
1359 \mc Set stroke color to that with one-character name c.
1360 \m(cl Set stroke color to that with two-character name cl.
1361 \m[color]
1362 Set stroke color to that with arbitrarily long name color.
1363 \m[] Restore previous stroke color.
1364 \Mc Set fill color to that with one-character name c.
1365 \M(cl Set fill color to that with two-character name cl.
1366 \M[color]
1367 Set fill color to that with arbitrarily long name color.
1368 \M[] Restore previous fill color.
1369 \nr Interpolate contents of register with one-character name r.
1370 \n(rg Interpolate contents of register with two-character name rg.
1371 \n[reg]
1372 Interpolate contents of register with arbitrarily long name reg.
1373 \N'n' Interpolate glyph with index n in the current font.
1374 \o'abc...'
1375 Overstrike centered glyphs of characters a, b, c, and so on.
1376 \O0 At the outermost suppression level, disable emission of glyphs
1377 and geometric objects to the output driver.
1378 \O1 At the outermost suppression level, enable emission of glyphs
1379 and geometric objects to the output driver.
1380 \O2 At the outermost suppression level, enable glyph and geometric
1381 primitive emission to the output driver and write to the stan‐
1382 dard error stream the page number, four bounding box registers
1383 enclosing glyphs written since the previous \O escape sequence,
1384 the page offset, line length, image file name (if any), horizon‐
1385 tal and vertical device motion quanta, and input file name.
1386 \O3 Begin a nested suppression level.
1387 \O4 End a nested suppression level.
1388 \O[5Pfile]
1389 At the outermost suppression level, write the name file to the
1390 standard error stream at position P, which must be one of l, r,
1391 c, or i.
1392 \p Break output line at next word boundary; adjust if applicable.
1393 \r Move “in reverse” (upward) 1 em.
1394 \R'name ±N'
1395 Set, increment, or decrement register name by N.
1396 \s±N Set/increase/decrease the type size to/by N scaled points. N
1397 must be a single digit; 0 restores the previous type size. (In
1398 compatibility mode only, a non-zero N must be in the range
1399 4–39.) Otherwise, as .ps request.
1400 \s(±N
1401 \s±(N Set/increase/decrease the type size to/by N scaled points; N is
1402 a two-digit number ≥1. As .ps request.
1403 \s[±N]
1404 \s±[N]
1405 \s'±N'
1406 \s±'N' Set/increase/decrease the type size to/by N scaled points. As
1407 .ps request.
1408 \S'N' Slant output glyphs by N degrees; the direction of text flow is
1409 positive.
1410 \t Interpolate a tab in copy mode.
1411 \u Move upward ½ em on typesetters.
1412 \v'N' Vertically move the drawing position by N vees (or specified
1413 units); | may be used. Positive motion is downward.
1414 \Ve Interpolate contents of environment variable with one-character
1415 name e.
1416 \V(ev Interpolate contents of environment variable with two-character
1417 name ev.
1418 \V[env]
1419 Interpolate contents of environment variable with arbitrarily
1420 long name env.
1421 \w'anything'
1422 Interpolate width of anything, formatted in a dummy environment.
1423 \x'N' Increase vertical spacing of pending output line by N vees (or
1424 specified units; negative before, positive after).
1425 \X'anything'
1426 Write anything to troff output as a device control command.
1427 Within anything, the escape sequences \&, \), \%, and \: are ig‐
1428 nored; \space and \~ are converted to single space characters;
1429 and \\ has its escape character stripped. So that the basic
1430 Latin subset of the Unicode character set can be reliably en‐
1431 coded in anything, the special character escape sequences \-,
1432 \[aq], \[dq], \[ga], \[ha], \[rs], and \[ti] are mapped to basic
1433 Latin characters; see groff_char(7). For this transformation,
1434 character translations and special character definitions are ig‐
1435 nored.
1436 \Yn Write contents of macro or string n to troff output as a device
1437 control command.
1438 \Y(nm Write contents of macro or string nm to troff output as a device
1439 control command.
1440 \Y[name]
1441 Write contents of macro or string name to troff output as a de‐
1442 vice control command.
1443 \zc Format character c with zero width—without advancing the drawing
1444 position.
1445 \Z'anything'
1446 Save the drawing position, format anything, then restore it.
1447 Drawing commands
1449 Drawing commands direct the output device to render geometrical objects
1450 rather than glyphs. Specific devices may support only a subset, or may
1451 feature additional ones; consult the man page for the output driver in
1452 use. Terminal devices in particular implement almost none.
1453 Rendering starts at the drawing position; when finished, the drawing
1455 position is left at the rightmost point of the object, even for closed
1456 figures, except where noted. GNU troff draws stroked (outlined) ob‐
1457 jects with the stroke color, and shades filled ones with the fill
1458 color. See section “Colors” above. Coordinates h and v are horizontal
1459 and vertical motions relative to the drawing position or previous point
1460 in the command. The default scaling unit for horizontal measurements
1461 (and diameters of circles) is m; for vertical ones, v.
1462 Circles, ellipses, and polygons can be drawn stroked or filled. These
1464 are independent properties; if you want a filled, stroked figure, you
1465 must draw the same figure twice using each drawing command. A filled
1466 figure is always smaller than an outlined one because the former is
1467 drawn only within its defined area, whereas strokes have a line thick‐
1468 ness (set with \D't').
1469 \D'~ h1 v1 ... hn vn'
1471 Draw B-spline to each point in sequence, leaving drawing posi‐
1472 tion at (hn, vn).
1473 \D'a hc vc h v'
1474 Draw circular arc centered at (hc, vc) counterclockwise from the
1475 drawing position to a point (h, v) relative to the center.
1476 (hc, vc) is adjusted to the point nearest the perpendicular bi‐
1477 sector of the arc's chord.
1478 \D'c d'
1479 Draw circle of diameter d with its leftmost point at the drawing
1480 position.
1481 \D'C d'
1482 As \D'C', but the circle is filled.
1483 \D'e h v'
1484 Draw ellipse of width h and height v with its leftmost point at
1485 the drawing position.
1486 \D'E h v'
1487 As \D'e', but the ellipse is filled.
1488 \D'l h v'
1489 Draw line from the drawing position to (h, v).
1490 \D'p h1 v1 ... hn vn'
1491 Draw polygon with vertices at drawing position and each point in
1492 sequence. GNU troff closes the polygon by drawing a line from
1493 (hn, vn) back to the initial drawing position. Afterward, the
1494 drawing position is left at (hn, vn).
1495 \D'P h1 v1 ... hn vn'
1496 As \D'p', but the polygon is filled.
1497 \D't n'
1498 Set stroke thickness of geometric objects to to n basic units.
1499 A zero n selects the minimal supported thickness. A negative n
1500 selects a thickness proportional to the type size; this is the
1501 default.
1502 Device control commands
1504 The .device and .devicem requests, and \X and \Y escape sequences, en‐
1505 able documents to pass information directly to a postprocessor. These
1506 are useful for exercising device-specific capabilities that the groff
1507 language does not abstract or generalize; such functions include the
1508 embedding of hyperlinks and image files. Device-specific functions are
1509 documented in each output driver's man page.
1510
1512 groff supports strings primarily for user convenience. Conventionally,
1513 if one would define a macro only to interpolate a small amount of text,
1514 without invoking requests or calling any other macros, one defines a
1515 string instead. Only one string is predefined by the language.
1516 \*[.T] Contains the name of the output device (for example, “utf8”
1518 or “pdf”).
1519 The .ds request creates a string with a specified name and contents.
1521 If the identifier named by .ds already exists as an alias, the target
1522 of the alias is redefined. If .ds is called with only one argument,
1523 the named string becomes empty. Otherwise, troff stores the remainder
1524 of the control line in copy mode; see subsection “Copy mode” below.
1525 The \* escape sequence dereferences a string's name, interpolating its
1527 contents. If the name does not exist, it is defined as empty, nothing
1528 is interpolated, and a warning in category “mac” is emitted. See sec‐
1529 tion “Warnings” in troff(1). The bracketed interpolation form accepts
1530 arguments that are handled as macro arguments are; see section “Calling
1531 macros” above. In contrast to macro calls, however, if a closing
1532 bracket ] occurs in a string argument, that argument must be enclosed
1533 in double quotes. \* is interpreted even in copy mode. When defining
1534 strings, argument interpolations must be escaped if they are to refer‐
1535 ence parameters from the calling context; see section “Parameters” be‐
1536 low.
1537 An initial neutral double quote " in the string contents is stripped to
1539 allow embedding of leading spaces. Any other " is interpreted liter‐
1540 ally, but it is wise to use the special character escape sequence \[dq]
1541 instead if the string might be interpolated as part of a macro argu‐
1542 ment; see section “Calling macros” above. Strings are not limited to a
1543 single input line of text. \newline works just as it does elsewhere.
1544 The resulting string is stored without the newlines. Care is therefore
1545 required when interpolating strings while filling is disabled. It is
1546 not possible to embed a newline in a string that will be interpreted as
1547 such when the string is interpolated. To achieve that effect, use \*
1548 to interpolate a macro instead.
1549 The .as request is similar to .ds but appends to a string instead of
1551 redefining it. If .as is called with only one argument, no operation
1552 is performed (beyond dereferencing the string).
1553 Because strings are similar to macros, they too can be defined to sup‐
1555 press AT&T troff compatibility mode enablement when interpolated; see
1556 section “Compatibility mode” below. The .ds1 request defines a string
1557 that suspends compatibility mode when the string is later interpolated.
1558 .as1 is likewise similar to .as, with compatibility mode suspended when
1559 the appended portion of the string is later interpolated.
1560 Caution: Unlike other requests, the second argument to these requests
1562 consumes the remainder of the input line, including trailing spaces.
1563 Ending string definitions (and appendments) with a comment, even an
1564 empty one, prevents unwanted space from creeping into them during
1565 source document maintenance.
1566 Several requests exist to perform rudimentary string operations.
1568 Strings can be queried (.length) and modified (.chop, .substring,
1569 .stringup, .stringdown), and their names can be manipulated through re‐
1570 naming, removal, and aliasing (.rn, .rm, .als).
1571 When a request, macro, string, or diversion is aliased, redefinitions
1573 and appendments “write through” alias names. To replace an alias with
1574 a separately defined object, you must use the rm request on its name
1575 first.
1576
1578 In the roff language, numbers can be stored in registers. Many built-
1579 in registers exist, supplying anything from the date to details of for‐
1580 matting parameters. You can also define your own. See section “Iden‐
1581 tifiers” above for information on constructing a valid name for a reg‐
1582 ister.
1583 Define registers and update their values with the nr request or the \R
1585 escape sequence.
1586 Registers can also be incremented or decremented by a configured amount
1588 at the time they are interpolated. The value of the increment is spec‐
1589 ified with a third argument to the .nr request, and a special interpo‐
1590 lation syntax, \n± is used to alter and then retrieve the register's
1591 value. Together, these features are called auto-increment. (A nega‐
1592 tive auto-increment can be considered an “auto-decrement”.)
1593 Many predefined registers are available. In the following presenta‐
1595 tion, the register interpolation syntax \n[name] is used to refer to a
1596 register name to clearly distinguish it from a string or request name.
1597 The register name space is separate from that used for requests,
1598 macros, strings, and diversions. Bear in mind that the symbols \n[]
1599 are not part of the register name.
1600 Read-only registers
1602 Predefined registers whose identifiers start with a dot are read-only.
1603 Many are Boolean-valued. Some are string-valued, meaning that they in‐
1604 terpolate text. A register name (without the dot) is often associated
1605 with a request of the same name; exceptions are noted.
1606 \n[.$] Count of arguments passed to currently interpolated
1608 macro or string.
1609 \n[.a] Amount of extra post-vertical line space; see \x.
1610 \n[.A] Approximate output is being formatted (Boolean-valued);
1611 see troff -a option.
1612 \n[.b] Font emboldening offset; see .bd.
1613 \n[.br] The normal control character was used to call the cur‐
1614 rently interpolated macro (Boolean-valued).
1615 \n[.c] Input line number; see .lf and register “c.”.
1616 \n[.C] Compatibility mode is enabled (Boolean-valued); see .cp.
1617 Always false when processing .do; see register .cp.
1618 \n[.cdp] Depth of last glyph formatted in the environment; posi‐
1619 tive if glyph extends below the baseline.
1620 \n[.ce] Count of output lines remaining to be centered.
1621 \n[.cht] Height of last glyph formatted in the environment; posi‐
1622 tive if glyph extends above the baseline.
1623 \n[.color] Color output is enabled (Boolean-valued).
1624 \n[.cp] Within .do, the saved value of compatibility mode; see
1625 register .C.
1626 \n[.csk] Skew of the last glyph formatted in the environment;
1627 skew is how far to the right of the center of a glyph
1628 the center of an accent over that glyph should be
1629 placed.
1630 \n[.d] Vertical drawing position in diversion.
1631 \n[.ev] Name of environment (string-valued).
1632 \n[.f] Mounting position of selected font; see .ft and \f.
1633 \n[.F] Name of input file (string-valued); see .lf.
1634 \n[.fam] Name of default font family (string-valued).
1635 \n[.fn] Resolved name of selected font (string-valued); see .ft
1636 and \f.
1637 \n[.fp] Next non-zero free font mounting position index.
1638 \n[.g] Always true in GNU troff (Boolean-valued).
1639 \n[.h] Text baseline high-water mark on page or in diversion.
1640 \n[.H] Horizontal motion quantum of output device in basic
1641 units.
1642 \n[.height] Font height; see \H.
1643 \n[.hla] Hyphenation language in environment (string-valued).
1644 \n[.hlc] Count of immediately preceding consecutive hyphenated
1645 lines in environment.
1646 \n[.hlm] Maximum quantity of consecutive hyphenated lines allowed
1647 in environment.
1648 \n[.hy] Automatic hyphenation mode in environment.
1649 \n[.hym] Hyphenation margin in environment.
1650 \n[.hys] Hyphenation space adjustment threshold in environment.
1651 \n[.i] Indentation amount; see .in.
1652 \n[.in] Indentation amount applicable to the pending output
1653 line; see .ti.
1654 \n[.int] Previous output line was “interrupted” or continued with
1655 \c (Boolean-valued).
1656 \n[.j] Adjustment mode encoded as an integer; see .ad and .na.
1657 Do not interpret or perform arithmetic on its value.
1658 \n[.k] Horizontal drawing position relative to indentation.
1659 \n[.kern] Pairwise kerning is enabled (Boolean-valued).
1660 \n[.l] Line length; see .ll.
1661 \n[.L] Line spacing; see .ls.
1662 \n[.lg] Ligature mode.
1663 \n[.linetabs] Line-tabs mode is enabled (Boolean-valued).
1664 \n[.ll] Line length applicable to the pending output line.
1665 \n[.lt] Title length.
1666 \n[.m] Stroke color (string-valued); see .gcolor and \m. Empty
1667 if the stroke color is the default.
1668 \n[.M] Fill color (string-valued); see .fcolor and \M. Empty
1669 if the fill color is the default.
1670 \n[.n] Length of formatted output on previous output line.
1671 \n[.ne] Amount of vertical space required by last .ne that
1672 caused a trap to be sprung; also see register .trunc.
1673 \n[.nm] Output line numbering is enabled (Boolean-valued).
1674 \n[.nn] Count of output lines remaining to have numbering sup‐
1675 pressed.
1676 \n[.ns] No-space mode is enabled (Boolean-valued).
1677 \n[.o] Page offset; see .po.
1678 \n[.O] Output suppression nesting level; see \O.
1679 \n[.p] Page length; see .pl.
1680 \n[.P] The page is selected for output (Boolean-valued); see
1681 troff -o option.
1682 \n[.pe] Page ejection is in progress (Boolean-valued).
1683 \n[.pn] Number of the next page.
1684 \n[.ps] Type size in scaled points.
1685 \n[.psr] Most recently requested type size in scaled points; see
1686 .ps and \s.
1687 \n[.pvs] Post-vertical line spacing.
1688 \n[.R] Count of available unused registers; always 10,000 in
1689 GNU troff.
1690 \n[.rj] Count of lines remaining to be right-aligned.
1691 \n[.s] Type size in points as a decimal fraction (string-val‐
1692 ued); see .ps and \s.
1693 \n[.slant] Slant of font in degrees; see \S.
1694 \n[.sr] Most recently requested type size in points as a decimal
1695 fraction (string-valued); see .ps and \s.
1696 \n[.ss] Size of minimal inter-word space in twelfths of the
1697 space width of the selected font.
1698 \n[.sss] Size of additional inter-sentence space in twelfths of
1699 the space width of the selected font.
1700 \n[.sty] Selected abstract style (string-valued); see .ft and \f.
1701 \n[.t] Distance to next vertical position trap; see .wh and
1702 .ch.
1703 \n[.T] An output device was explicitly selected (Boolean-val‐
1704 ued); see troff -T option.
1705 \n[.tabs] Representation of tab settings suitable for use as argu‐
1706 ment to .ta (string-valued).
1707 \n[.trunc] Amount of vertical space truncated by the most recently
1708 sprung vertical position trap, or, if the trap was
1709 sprung by an .ne, minus the amount of vertical motion
1710 produced by .ne; also see register .ne.
1711 \n[.u] Filling is enabled (Boolean-valued); see .fi and .nf.
1712 \n[.U] Unsafe mode is enabled (Boolean-valued); see troff -U
1713 option.
1714 \n[.v] Vertical line spacing; see .vs.
1715 \n[.V] Vertical motion quantum of the output device in basic
1716 units.
1717 \n[.vpt] Vertical position traps are enabled (Boolean-valued).
1718 \n[.w] Width of previous glyph formatted in the environment.
1719 \n[.warn] Sum of the numeric codes of enabled warning categories.
1720 \n[.x] Major version number of the running troff formatter.
1721 \n[.y] Minor version number of the running troff formatter.
1722 \n[.Y] Revision number of the running troff formatter.
1723 \n[.z] Name of diversion (string-valued). Empty if output is
1724 directed to the top-level diversion.
1725 \n[.zoom] Zoom multiplier of current font (in thousandths; zero if
1726 no magnification); see .fzoom.
1727 Writable predefined registers
1729 Several registers are predefined but also modifiable; some are updated
1730 upon interpretation of certain requests or escape sequences. Date- and
1731 time-related registers are set to the local time as determined by
1732 localtime(3) when the formatter launches. This initialization can be
1733 overridden by SOURCE_DATE_EPOCH and TZ; see section “Environment” of
1734 groff(1).
1735 \n[$$] Process ID of troff.
1737 \n[%] Page number.
1738 \n[c.] Input line number.
1739 \n[ct] Union of character types of each glyph rendered into
1740 dummy environment by \w.
1741 \n[dl] Width of last closed diversion.
1742 \n[dn] Height of last closed diversion.
1743 \n[dw] Day of the week (1–7; 1 is Sunday).
1744 \n[dy] Day of the month (1–31).
1745 \n[hours] Count of hours elapsed since midnight (0–23).
1746 \n[hp] Horizontal drawing position relative to start of input
1747 line.
1748 \n[llx] Lower-left x coordinate (in PostScript units) of Post‐
1749 Script image; see .psbb.
1750 \n[lly] Lower-left y coordinate (in PostScript units) of Post‐
1751 Script image; see .psbb.
1752 \n[ln] Output line number; see .nm.
1753 \n[lsn] Count of leading spaces on input line.
1754 \n[lss] Amount of horizontal space corresponding to leading spa‐
1755 ces on input line.
1756 \n[minutes] Count of minutes elapsed in the hour (0–59).
1757 \n[mo] Month of the year (1–12).
1758 \n[nl] Vertical drawing position.
1759 \n[opmaxx]
1760 \n[opmaxy]
1761 \n[opminx]
1762 \n[opminy] These four registers mark the top left- and bottom
1763 right-hand corners of a rectangle encompassing all for‐
1764 matted output on the page. They are reset to -1 by \O0
1765 or \O1.
1766 \n[rsb] As register sb, adding maximum glyph height to measure‐
1767 ment.
1768 \n[rst] As register st, adding maximum glyph depth to measure‐
1769 ment.
1770 \n[sb] Maximum displacement of text baseline below its original
1771 position after rendering into dummy environment by \w.
1772 \n[seconds] Count of seconds elapsed in the minute (0–60).
1773 \n[skw] Skew of last glyph rendered into dummy environment by
1774 \w.
1775 \n[slimit] The maximum depth of troff's internal input stack. If
1776 ≤0, there is no limit: recursion can continue until
1777 available memory is exhausted. The default is 1,000.
1778 \n[ssc] Subscript correction of last glyph rendered into dummy
1779 environment by \w.
1780 \n[st] Maximum displacement of text baseline above its original
1781 position after rendering into dummy environment by \w.
1782 \n[systat] Return value of system() function; see .sy.
1783 \n[urx] Upper-right x coordinate (in PostScript units) of Post‐
1784 Script image; see .psbb.
1785 \n[ury] Upper-right y coordinate (in PostScript units) of Post‐
1786 Script image; see .psbb.
1787 \n[year] Gregorian year.
1788 \n[yr] Gregorian year minus 1900.
1789
1791 In digital typography, a font is a collection of characters in a spe‐
1792 cific typeface that a device can render as glyphs at a desired size.
1793 (Terminals and some output devices have fonts that render at only one
1794 or two sizes. As examples of the latter, take the groff lj4 device's
1795 Lineprinter, and lbp's Courier and Elite faces.) A roff formatter can
1796 change typefaces at any point in the text. The basic faces are a set
1797 of styles combining upright and slanted shapes with normal and heavy
1798 stroke weights: “R”, “I”, “B”, and “BI”—these stand for roman, bold,
1799 italic, and bold-italic. For linguistic text, GNU troff groups type‐
1800 faces into families containing each of these styles. (Font designers
1801 prepare families such that the styles share esthetic properties.) A
1802 text font is thus often a family combined with a style, but it need not
1803 be: consider the ps and pdf devices' ZCMI (Zapf Chancery Medium
1804 italic)—often, no other style of Zapf Chancery Medium is provided. On
1805 typesetting devices, at least one special font is available, comprising
1806 unstyled glyphs for mathematical operators and other purposes.
1807 Like AT&T troff, GNU troff does not itself load or manipulate a digital
1809 font file; instead it works with a font description file that charac‐
1810 terizes it, including its glyph repertoire and the metrics (dimensions)
1811 of each glyph. This information permits the formatter to accurately
1812 place glyphs with respect to each other. Before using a font descrip‐
1813 tion, the formatter associates it with a mounting position, a place in
1814 an ordered list of available typefaces. So that a document need not be
1815 strongly coupled to a specific font family, in GNU troff an output de‐
1816 vice can associate a style in the abstract sense with a mounting posi‐
1817 tion. Thus the default family can be combined with a style dynami‐
1818 cally, producing a resolved font name.
1819 Fonts often have trademarked names, and even Free Software fonts can
1821 require renaming upon modification. groff maintains a convention that
1822 a device's serif font family is given the name T (“Times”), its sans-
1823 serif family H (“Helvetica”), and its monospaced family C (“Courier”).
1824 Historical inertia has driven groff's font identifiers to short upper‐
1825 case abbreviations of font names, as with TR, TB, TI, TBI, and a spe‐
1826 cial font S.
1827 The default family used with abstract styles can be changed at any
1829 time; initially, it is T. Typically, abstract styles are arranged in
1830 the first four mounting positions in the order shown above. The de‐
1831 fault mounting position, and therefore style, is always 1 (R). By is‐
1832 suing appropriate formatter instructions, you can override these de‐
1833 faults before your document writes its first glyph.
1834 Terminal output devices cannot change font families and lack special
1836 fonts. They support style changes by overstriking, or by altering
1837 ISO 6429/ECMA-48 graphic renditions (character cell attributes).
1838
1840 When filling, groff hyphenates words as needed at user-specified and
1841 automatically determined hyphenation points. Explicitly hyphenated
1842 words such as “mother-in-law” are always eligible for breaking after
1843 each of their hyphens. The hyphenation character \% and non-printing
1844 break point \: escape sequences may be used to control the hyphenation
1845 and breaking of individual words. The .hw request sets user-defined
1846 hyphenation points for specified words at any subsequent occurrence.
1847 Otherwise, groff determines hyphenation points automatically by de‐
1848 fault.
1849 Several requests influence automatic hyphenation. Because conventions
1851 vary, a variety of hyphenation modes is available to the .hy request;
1852 these determine whether hyphenation will apply to a word prior to
1853 breaking a line at the end of a page (more or less; see below for de‐
1854 tails), and at which positions within that word automatically deter‐
1855 mined hyphenation points are permissible. The default is “1” for his‐
1856 torical reasons, but this is not an appropriate value for the English
1857 hyphenation patterns used by groff; localization macro files loaded by
1858 troffrc and macro packages often override it.
1859 0 disables hyphenation.
1861 1 enables hyphenation except after the first and before the last
1863 character of a word.
1864 The remaining values “imply” 1; that is, they enable hyphenation under
1866 the same conditions as “.hy 1”, and then apply or lift restrictions
1867 relative to that basis.
1868 2 disables hyphenation of the last word on a page. (Hyphenation
1870 is prevented if the next page location trap is closer to the
1871 vertical drawing position than the next text baseline would be.
1872 See section “Traps” below.)
1873 4 disables hyphenation before the last two characters of a word.
1875 8 disables hyphenation after the first two characters of a word.
1877 16 enables hyphenation before the last character of a word.
1879 32 enables hyphenation after the first character of a word.
1881 Apart from value 2, restrictions imposed by the hyphenation mode are
1883 not respected for words whose hyphenations have been specified with the
1884 hyphenation character (“\%” by default) or the .hw request.
1885 Nonzero values are additive. For example, mode 12 causes groff to hy‐
1887 phenate neither the last two nor the first two characters of a word.
1888 Some values cannot be used together because they contradict; for in‐
1889 stance, values 4 and 16, and values 8 and 32. As noted, it is super‐
1890 fluous to add 1 to any non-zero even mode.
1891 The places within a word that are eligible for hyphenation are deter‐
1893 mined by language-specific data (.hla, .hpf, and .hpfa) and lettercase
1894 relationships (.hcode and .hpfcode). Furthermore, hyphenation of a
1895 word might be suppressed due to a limit on consecutive hyphenated lines
1896 (.hlm), a minimum line length threshold (.hym), or because the line can
1897 instead be adjusted with additional inter-word space (.hys).
1898
1900 The set of hyphenation patterns is associated with the hyphenation lan‐
1901 guage set by the .hla request. The .hpf request is usually invoked by
1902 a localization file loaded by the troffrc file. groff provides local‐
1903 ization files for several languages; see groff_tmac(5).
1904
1906 The .de request defines a macro named for its argument. If that name
1907 already exists as an alias, the target of the alias is redefined; see
1908 section “Strings” above. troff enters “copy mode” (see below), storing
1909 subsequent input lines as the definition. If the optional second argu‐
1910 ment is not specified, the definition ends with the control line “..”
1911 (two dots). Alternatively, a second argument names a macro whose call
1912 syntax ends the definition; this “end macro” is then called normally.
1913 Spaces or tabs are permitted after the first control character in the
1914 line containing this ending token, but a tab immediately after the to‐
1915 ken prevents its recognition as the end of a macro definition. Macro
1916 definitions can be nested if they use distinct end macros or if their
1917 ending tokens are sufficiently escaped. An end macro need not be de‐
1918 fined until it is called. This fact enables a nested macro definition
1919 to begin inside one macro and end inside another.
1920 Variants of .de disable compatibility mode and/or indirect the names of
1922 the macros specified for definition or termination: these are .de1,
1923 .dei, and .dei1. Append to macro definitions with .am, .am1, .ami, and
1924 .ami1. The .als, .rm, and .rn requests create an alias of, remove, and
1925 rename a macro, respectively. .return stops the execution of a macro
1926 immediately, returning to the enclosing context.
1927 Parameters
1929 Macro call and string interpolation parameters can be accessed using
1930 escape sequences starting with “\$”. The \n[.$] read-only register
1931 stores the count of parameters available to a macro or string; its
1932 value can be changed by the .shift request, which dequeues parameters
1933 from the current list. The \$0 escape sequence interpolates the name
1934 by which a macro was called. Applying string interpolation to a macro
1935 does not change this name.
1936 Copy mode
1938 When troff processes certain requests, most importantly those which de‐
1939 fine or append to a macro or string, it does so in copy mode: it copies
1940 the characters of the definition into a dedicated storage region, in‐
1941 terpolating the escape sequences \n, \g, \$, \*, \V, and \? normally;
1942 interpreting \newline immediately; discarding comments \" and \#; in‐
1943 terpolating the current leader, escape, or tab character with \a, \e,
1944 and \t, respectively; and storing all other escape sequences in an en‐
1945 coded form. The complement of copy mode—a roff formatter's behavior
1946 when not defining or appending to a macro, string, or diversion—where
1947 all macros are interpolated, requests invoked, and valid escape se‐
1948 quences processed immediately upon recognition, can be termed interpre‐
1949 tation mode.
1950 The escape character, \ by default, can escape itself. This enables
1952 you to control whether a given \n, \g, \$, \*, \V, or \? escape se‐
1953 quence is interpreted at the time the macro containing it is defined,
1954 or later when the macro is called.
1955 You can think of \\ as a “delayed” backslash; it is the escape charac‐
1957 ter followed by a backslash from which the escape character has removed
1958 its special meaning. Consequently, \\ is not an escape sequence in the
1959 usual sense. In any escape sequence \X that troff does not recognize,
1960 the escape character is ignored and X is output. An unrecognized es‐
1961 cape sequence causes a warning in category “escape”, with two excep‐
1962 tions, \\ being one. The other is \., which escapes the control char‐
1963 acter. It is used to permit nested macro definitions to end without a
1964 named macro call to conclude them. Without a syntax for escaping the
1965 control character, this would not be possible. roff documents should
1966 not use the \\ or \. character sequences outside of copy mode; they
1967 serve only to obfuscate the input. Use \e to represent the escape
1968 character, \[rs] to obtain a backslash glyph, and \& before . and '
1969 where troff expects them as control characters if you mean to use them
1970 literally.
1971 Macro definitions can be nested to arbitrary depth. In “\\”, each es‐
1973 cape character is interpreted twice—once in copy mode, when the macro
1974 is defined, and once in interpretation mode, when the macro is called.
1975 This fact leads to exponential growth in the quantity of escape charac‐
1976 ters required to delay interpolation of \n, \g, \$, \*, \V, and \? at
1977 each nesting level. An alternative is to use \E, which represents an
1978 escape character that is not interpreted in copy mode. Because \. is
1979 not a true escape sequence, we can't use \E to keep “..” from ending a
1980 macro definition prematurely. If the multiplicity of backslashes com‐
1981 plicates maintenance, use end macros.
1982
1984 Traps are locations in the output, or conditions on the input that,
1985 when reached or fulfilled, call a specified macro. A vertical position
1986 trap calls a macro when the formatter's vertical drawing position
1987 reaches or passes, in the downward direction, a certain location on the
1988 output page or in a diversion. Its applications include setting page
1989 headers and footers, body text in multiple columns, and footnotes.
1990 These traps can occur at a given location on the page (.wh, .ch); at a
1991 given location in the current diversion (.dt)—together, these are known
1992 as vertical position traps, which can be disabled and re-enabled
1993 (.vpt).
1994 A diversion is not formatted in the context of a page, so it lacks page
1996 location traps; instead it can have a diversion trap. There can exist
1997 at most one such vertical position trap per diversion.
1998 Other kinds of trap can be planted at a blank line (.blm); at a line
2000 with leading space characters (.lsm); after a certain number of produc‐
2001 tive input lines (.it, .itc); or at the end of input (.em). Macros
2002 called by traps are passed no arguments. Setting a trap is also called
2003 planting one. It is said that a trap is sprung if its condition is
2004 fulfilled.
2005 Registers associated with trap management include vertical position
2007 trap enablement status (\n[.vpt]), distance to the next trap (\n[.t]),
2008 amount of needed (.ne-requested) space that caused the most recent ver‐
2009 tical position trap to be sprung (\n[.ne]), amount of needed space
2010 truncated from the amount requested (\n[.trunc]), page ejection status
2011 (\n[.pe]), and leading space count (\n[.lsn]) with its corresponding
2012 amount of motion (\n[.lss]).
2013 Page location traps
2015 A page location trap is a vertical position trap that applies to the
2016 page; that is, to undiverted output. Many can be present; manage them
2017 with the wh and ch requests. Non-negative page locations given to
2018 these requests set the trap relative to the top of the page; negative
2019 values set the trap relative to the bottom of the page. It is not pos‐
2020 sible to plant a trap less than one basic unit from the page bottom: a
2021 location of “-0” is interpreted as “0”, the top of the page. An exist‐
2022 ing visible trap (see below) at the same location is removed; this is
2023 .wh's sole function if its second argument is missing.
2024 A trap is sprung only if it is visible, meaning that its location is
2026 reachable on the page and it is not hidden by another trap at the same
2027 location already planted there. (A trap planted at “20i” or “-30i”
2028 will not be sprung on a page of length “11i”.)
2029 A trap above the top or at or below the bottom of the page can be made
2031 visible by either moving it into the page area or increasing the page
2032 length so that the trap is on the page. Negative trap values always
2033 use the current page length; they are not converted to an absolute ver‐
2034 tical position. Use .ptr to dump page location traps to the standard
2035 error stream; their positions are reported in basic units.
2036 The implicit page trap
2038 An implicit page trap always exists in the top-level diversion; it
2039 works like a trap in some ways but not others. Its purpose is to eject
2040 the current page and start the next one. It has no name, so it cannot
2041 be moved or deleted with wh or ch requests. You cannot hide it by
2042 placing another trap at its location, and can move it only by redefin‐
2043 ing the page length with .pl. Its operation is suppressed when verti‐
2044 cal page traps are disabled with the vpt request.
2045
2047 In roff systems it is possible to format text as if for output, but in‐
2048 stead of writing it immediately, one can divert the formatted text into
2049 a named storage area. It is retrieved later by specifying its name af‐
2050 ter a control character. The same name space is used for such diver‐
2051 sions as for strings and macros; see section “Identifiers” above. Such
2052 text is sometimes said to be “stored in a macro”, but this coinage ob‐
2053 scures the important distinction between macros and strings on one hand
2054 and diversions on the other; the former store unformatted input text,
2055 and the latter capture formatted output. Diversions also do not inter‐
2056 pret arguments. Applications of diversions include “keeps” (preventing
2057 a page break from occurring at an inconvenient place by forcing a set
2058 of output lines to be set as a group), footnotes, tables of contents,
2059 and indices. For orthogonality it is said that GNU troff is in the
2060 top-level diversion if no diversion is active (that is, formatted out‐
2061 put is being “diverted” immediately to the output device.
2062 Dereferencing an undefined diversion will create an empty one of that
2064 name and cause a warning in category mac to be emitted. (see section
2065 “Warnings” in troff(1)). A diversion does not exist for the purpose of
2066 testing with the d conditional operator until its initial definition
2067 ends (see subsection “Conditional expressions” above).
2068 The di request creates a diversion, including any partially collected
2070 line. da appends to a diversion, creating one if it does not already
2071 exist. If the diversion's name already exists as an alias, the target
2072 of the alias is replaced or appended to; see section “Strings” above.
2073 box and boxa works similarly, but ignore partially collected lines.
2074 Call any of these macros again without an argument to end the diver‐
2075 sion.
2076 Diversions can be nested. The registers .d, .z, dn, and dl report in‐
2078 formation about the current (or last closed) diversion. .h is meaning‐
2079 ful in diversions, including the top level.
2080 The \! and \? escape sequences and output request escape from a di‐
2082 version, the first two to the enclosing level and the last to the top
2083 level. This facility is termed transparent embedding.
2084 The asciify and unformat requests reprocess diversions.
2086
2088 Macros, strings, and diversions share a name space; see section “Iden‐
2089 tifiers” above. Internally, the same mechanism is used to store them.
2090 You can thus call a macro with string interpolation syntax and vice
2091 versa. Interpolating a string does not hide existing macro arguments.
2092 The sequence \\ can be placed at the end of a line in a macro defini‐
2093 tion or, within a macro definition, immediately after the interpolation
2094 of a macro as a string to suppress the effect of a newline.
2095
2097 Environments store most of the parameters that control text processing.
2098 A default environment named “0” exists when troff starts up; it is mod‐
2099 ified by formatting-related requests and escape sequences.
2100 You can create new environments and switch among them. Only one is
2102 current at any given time. Active environments are managed using a
2103 stack, a data structure supporting “push” and “pop” operations. The
2104 current environment is at the top of the stack. The same environment
2105 name can be pushed onto the stack multiple times, possibly interleaved
2106 with others. Popping the environment stack does not destroy the cur‐
2107 rent environment; it remains accessible by name and can be made current
2108 again by pushing it at any time. Environments cannot be renamed or
2109 deleted, and can only be modified when current. To inspect the envi‐
2110 ronment stack, use the pev request; see section “Debugging” below.
2111 Environments store the following information.
2113 • a partially collected line, if any
2115 • data about the most recently output glyph and line (registers .cdp,
2117 .cht, .csk, .n, .w)
2118 • typeface parameters (size, family, style, height and slant, inter-
2120 word and inter-sentence space sizes)
2121 • page parameters (line length, title length, vertical spacing, line
2123 spacing, indentation, line numbering, centering, right-alignment, un‐
2124 derlining, hyphenation parameters)
2125 • filling enablement; adjustment enablement and mode
2127 • tab stops; tab, leader, escape, control, no-break control, hyphena‐
2129 tion, and margin characters
2130 • input line traps
2132 • stroke and fill colors
2134 The ev request pushes to and pops from the environment stack, while evc
2136 copies a named environment's contents to the current one.
2137
2139 In RUNOFF (see roff(7)), underlining, even of lengthy passages, was
2140 straightforward because only fixed-pitch printing devices were tar‐
2141 geted. Typesetter output posed a greater challenge. There exists a
2142 groff request .ul (see above) that underlines subsequent source lines
2143 on terminal devices, but on typesetters, it selects an italic font
2144 style instead. The ms macro package (see groff_ms(7)) offers a macro
2145 .UL, but it too produces the desired effect only on typesetters, and
2146 has other limitations.
2147 One could adapt ms's approach to the construction of a macro as fol‐
2149 lows.
2150 .de UNDERLINE
2151 . ie n \\$1\f[I]\\$2\f[P]\\$3
2152 . el \\$1\Z'\\$2'\v'.25m'\D'l \w'\\$2'u 0'\v'-.25m'\\$3
2153 ..
2154 If doclifter(1) makes trouble, change the macro name UNDERLINE into
2155 some 2-letter word, like Ul. Moreover, change the form of the font se‐
2156 lection escape sequence from \f[P] to \fP.
2157 Underlining without macro definitions
2159 If one does not want to use macro definitions, e.g., when doclifter
2160 gets lost, use the following.
2161 .ds u1 before
2162 .ds u2 in
2163 .ds u3 after
2164 .ie n \*[u1]\f[I]\*[u2]\f[P]\*[u3]
2165 .el \*[u1]\Z'\*[u2]'\v'.25m'\D'l \w'\*[u2]'u 0'\v'-.25m'\*[u3]
2166 When using doclifter, it might be necessary to change syntax forms such
2167 as \[xy] and \*[xy] to those supported by AT&T troff: \*(xy and \(xy,
2168 and so on.
2169 Then these lines could look like
2171 .ds u1 before
2172 .ds u2 in
2173 .ds u3 after
2174 .ie n \*[u1]\fI\*(u2\fP\*(u3
2175 .el \*(u1\Z'\*(u2'\v'.25m'\D'l \w'\*(u2'u 0'\v'-.25m'\*(u3
2176 The result looks like
2178 before _i_n after
2179 Underlining by overstriking with \(ul
2181 The \z escape sequence writes a glyph without advancing the drawing po‐
2182 sition, enabling overstriking. Thus, \zc\(ul formats c with an under‐
2183 rule glyph on top of it. Video terminals implement the underrule by
2184 setting a character cell's underline attribute, so this technique works
2185 in both nroff and troff modes.
2186 Long words may then look intimidating in the input; a clarifying ap‐
2188 proach might be to use the input line continuation escape sequence
2189 \newline to place each underlined character on its own input line.
2190 Thus,
2191 .nf
2192 \&\fB: ${\fIvar\fR\c
2193 \zo\(ul\
2194 \zp\(ul\c
2195 \&\fIvalue\fB}
2196 .fi
2197 produces
2198 : ${varo_p_value}
2199 as output.
2200
2202 The differences between the roff language recognized by GNU troff and
2203 that of AT&T troff, as well as the device, font, and device-independent
2204 intermediate output formats described by CSTR #54 are documented in
2205 groff_diff(7). groff provides an AT&T compatibility mode. The .cp re‐
2206 quest and registers .C and .cp set and test the enablement of this
2207 mode.
2208
2210 Preprocessors use the .lf request to preserve the identities of line
2211 numbers and names of input files. groff emits a variety of error diag‐
2212 nostics and supports several categories of warning; the output of these
2213 can be selectively suppressed with .warn (and see the -E, -w, and -W
2214 options of troff(1)). A trace of the formatter's input processing
2215 stack can be emitted when errors or warnings occur by means of
2216 troff(1)'s -b option, or produced on demand with the .backtrace re‐
2217 quest. .tm, .tmc, and .tm1 can be used to emit customized diagnostic
2218 messages or for instrumentation while troubleshooting. .ex and .ab
2219 cause early termination with successful and error exit codes respec‐
2220 tively, to halt further processing when continuing would be fruitless.
2221 Examine the state of the formatter with requests that write lists of
2222 defined names—macros, strings, and diversions—(.pm); environments
2223 (.pev), registers (.pnr), and page location traps (.ptr) to the stan‐
2224 dard error stream.
2225
2227 This document was written by by Trent A. Fisher, Werner Lemberg, and G.
2228 Branden Robinson ⟨g.branden.robinson@gmail.com⟩. Section “Underlining”
2229 was primarily written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
2230
2232 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
2233 Lemberg, is the primary groff manual. You can browse it interactively
2234 with “info groff”.
2235 “Troff User's Manual” by Joseph F. Ossanna, 1976 (revised by Brian W.
2237 Kernighan, 1992), AT&T Bell Laboratories Computing Science Technical
2238 Report No. 54, widely called simply “CSTR #54”, documents the language,
2239 device and font description file formats, and device-independent output
2240 format referred to collectively in groff documentation as “AT&T troff”.
2241 “A Typesetter-independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell
2243 Laboratories Computing Science Technical Report No. 97 (CSTR #97), pro‐
2244 vides additional insights into the device and font description file
2245 formats and device-independent output format.
2246 groff(1)
2248 is the preferred interface to the groff system; it manages the
2249 pipeline that carries a source document through preprocessors,
2250 the troff formatter, and an output driver to viewable or print‐
2251 able form. It also exhaustively lists the man pages provided
2252 with the GNU roff system.
2253 groff_char(7)
2255 discusses character encoding issues, escape sequences that pro‐
2256 duce glyphs, and enumerates groff's predefined special character
2257 escape sequences.
2258 groff_diff(7)
2260 covers differences between the GNU troff formatter, its device
2261 and font description file formats, its device-independent output
2262 format, and those of AT&T troff, whose design it reimplements.
2263 groff_font(5)
2265 describes the formats of the files that describe devices (DESC)
2266 and fonts.
2267 groff_tmac(5)
2269 surveys macro packages provided with groff, describes how docu‐
2270 ments can take advantage of them, offers guidance on writing
2271 macro packages and using diversions, and includes historical in‐
2272 formation on macro package naming conventions.
2273 roff(7)
2275 presents a detailed history of roff systems and summarizes con‐
2276 cepts common to them.
2277groff 1.23.0 2 November 2023 groff(7)