1groff(7)               Miscellaneous Information Manual               groff(7)


6       groff - GNU roff language reference


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.
13       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.
20       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.
26       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.

Input format

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.

Syntax characters

43       Several input characters are syntactically significant to groff.
45       .   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.
51       '   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.
60       "   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).
68       \   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.
74       (   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.
78       [   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.
82       ]   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).
86       Additionally, the Control+A character (U+0001) in text  is  interpreted
87       as a leader (see below).
89       Horizontal  white space characters are significant to groff, but trail‐
90       ing spaces on text lines are ignored.
92       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.
106       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.
111       tab     A  tab character in text causes the drawing position to advance
112               to the next defined tab stop.

Tabs and leaders

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.

Line continuation

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


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


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.
174       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.
180       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.
192       The magnitudes of other scaling units depend on the text formatting pa‐
193       rameters in effect.
195       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.
200   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.
208   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.

Numeric expressions

220       A numeric expression evaluates to an integer.  The following  operators
221       are recognized.
223             +   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
251       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.)
259       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.
266       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.
271       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.
276       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).
282       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.
288       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.
300       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.
304       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.
309       +  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.
316       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.
325       The \B escape sequence tests its argument for validity as a numeric ex‐
326       pression.
328       A register interpolated as an operand in a numeric expression must have
329       an Arabic format; luckily, this is the default.
331       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.


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.
343       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”.
350       On a machine using the ISO 646, 8859, or 10646 character encodings, in‐
351       valid input characters are 0x00, 0x08, 0x0B, 0x0D0x1F, and  0x800x9F.
352       On  an  EBCDIC  host,  they are 0x000x01, 0x08, 0x09, 0x0B, 0x0D0x14,
353       0x170x1F, and 0x300x3F.  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.
357       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.
362       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.
366       The  escape  sequence  \A tests its argument for validity as an identi‐
367       fier.
369       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.
381       Identifiers for requests, macros, strings,  and  diversions  share  one
382       name space; special characters and character classes another.  No other
383       object types do.

Control characters

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

Invoking requests

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.
408       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.
415       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.
420       Spaces  and  tabs  immediately  after  a control character are ignored.
421       Commonly, authors structure the source of documents or macro files with
422       them.

Calling macros

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).
430       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.
434       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.
439       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.

Using escape sequences

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.
453       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).
466       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.
471       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.
475       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).


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.
487       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.
493       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.
498       Finally, the escape sequences \D, \h, \H, \l, \L, \N, \R, \s,  \S,  \v,
499       and \x prohibit many delimiters.
501              • the numerals 0–9 and the decimal point “.
503              • the (single-character) operators +-/*%<>=&:()
505              • any  escape  sequences  other than \%, \:, \{, \}, \', \`, \-,
506                \_, \!, \/, \c, \e, and \p
508       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).

Dummy characters

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.

Control structures

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.
536       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).
545       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.
551       \{  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.
560   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.
566       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).
581       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.
594       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.
601       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”,
604F”, “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.)

Syntax reference conventions

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

Request short reference

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).
650       .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),
796cmyk” (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.

Escape sequence short reference

1236       The escape sequences \", \#, \$, \*, \?, \a, \e, \n, \t,  \g,  \V,  and
1237       \newline are interpreted even in copy mode.
1239       \"     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.
1448   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.
1454       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.
1463       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').
1470       \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.
1503   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.


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.
1517       \*[.T]    Contains the name of the output device (for  example,  “utf8
1518                 or “pdf).
1520       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.
1526       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.
1538       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.
1550       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).
1554       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.
1561       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.
1567       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).
1572       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.


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.
1584       Define registers and update their values with the nr request or the  \R
1585       escape sequence.
1587       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”.)
1594       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.
1601   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.
1607       \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.
1728   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).
1736       \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.

Using fonts

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.
1808       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.
1820       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.
1828       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.
1835       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).


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.
1850       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.
1860       0      disables hyphenation.
1862       1      enables  hyphenation  except after the first and before the last
1863              character of a word.
1865       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.
1869       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.)
1874       4      disables hyphenation before the last two characters of a word.
1876       8      disables hyphenation after the first two characters of a word.
1878       16     enables hyphenation before the last character of a word.
1880       32     enables hyphenation after the first character of a word.
1882       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.
1886       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.
1892       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).


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

Writing macros

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.
1921       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.
1928   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.
1937   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.
1951       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.
1956       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.
1972       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.


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).
1995       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.
1999       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.
2006       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]).
2014   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.
2025       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”.)
2030       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.
2037   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.


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.
2063       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).
2069       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.
2077       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.
2081       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.
2085       The asciify and unformat requests reprocess diversions.

Punning names

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.


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.
2101       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.
2112       Environments store the following information.
2114       • a partially collected line, if any
2116       • data  about  the most recently output glyph and line (registers .cdp,
2117         .cht, .csk, .n, .w)
2119       • typeface parameters (size, family, style, height  and  slant,  inter-
2120         word and inter-sentence space sizes)
2122       • page  parameters  (line  length, title length, vertical spacing, line
2123         spacing, indentation, line numbering, centering, right-alignment, un‐
2124         derlining, hyphenation parameters)
2126       • filling enablement; adjustment enablement and mode
2128       • tab  stops;  tab, leader, escape, control, no-break control, hyphena‐
2129         tion, and margin characters
2131       • input line traps
2133       • stroke and fill colors
2135       The ev request pushes to and pops from the environment stack, while evc
2136       copies a named environment's contents to the current one.


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.
2148       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.
2158   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.
2170       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
2177       The result looks like
2178              before _i_n after
2180   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.
2187       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.

Compatibility mode

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.


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.


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

See also

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”.
2236       “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”.
2242       “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.
2247       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.
2254       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.
2259       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.
2264       groff_font(5)
2265              describes  the formats of the files that describe devices (DESC)
2266              and fonts.
2268       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.
2274       roff(7)
2275              presents  a detailed history of roff systems and summarizes con‐
2276              cepts common to them.
2280groff 1.23.0                    2 November 2023                       groff(7)