1troff(1) General Commands Manual troff(1)
2
6 troff - GNU roff typesetter and document formatter
7
9 troff [-abcCEiRUz] [-d ctext] [-d string=text] [-f font-family]
10 [-F font-directory] [-I inclusion-directory] [-m macro-package]
11 [-M macro-directory] [-n page-number] [-o page-list]
12 [-r cnumeric-expression] [-r register=numeric-expression]
13 [-T output-device] [-w warning-category] [-W warning-category]
14 [file ...]
15 troff --help
17 troff -v
19 troff --version
20
22 GNU troff transforms groff(7) language input into the device-indepen‐
23 dent output format described in groff_out(5); troff is thus the heart
24 of the GNU roff document formatting system. If no file operands are
25 given on the command line, or if file is “-”, the standard input stream
26 is read.
27 GNU troff is functionally compatible with the AT&T troff typesetter and
29 features numerous extensions. Many people prefer to use the groff(1)
30 command, a front end which also runs preprocessors and output drivers
31 in the appropriate order and with appropriate options.
32
34 -h and --help display a usage message, while -v and --version show ver‐
35 sion information; all exit afterward.
36 -a Generate a plain text approximation of the typeset output. The
38 read-only register .A is set to 1. This option produces a sort
39 of abstract preview of the formatted output.
40 • Page breaks are marked by a phrase in angle brackets; for ex‐
42 ample, “<beginning of page>”.
43 • Lines are broken where they would be in the formatted output.
45 • A horizontal motion of any size is represented as one space.
47 Adjacent horizontal motions are not combined. Inter-sentence
48 space nodes (those arising from the second argument to the .ss
49 request) are not represented.
50 • Vertical motions are not represented.
52 • Special characters are rendered in angle brackets; for exam‐
54 ple, the default soft hyphen character appears as “<hy>”.
55 The above description should not be considered a specification;
57 the details of -a output are subject to change.
58 -b Write a backtrace reporting the state of troff's input parser to
60 the standard error stream with each diagnostic message. The
61 line numbers given in the backtrace might not always be correct,
62 because troff's idea of line numbers can be confused by requests
63 that append to macros.
64 -c Start with color output disabled.
66 -C Enable AT&T troff compatibility mode; implies -c. See
68 groff_diff(7).
69 -d ctext
71 -d string=text
72 Define roff string c or string as text. c must be one charac‐
73 ter; string can be of arbitrary length. Such string assignments
74 happen before any macro file is loaded, including the startup
75 file. Due to getopt_long(3) limitations, c cannot be, and
76 string cannot contain, an equals sign, even though that is a
77 valid character in a roff identifier.
78 -E Inhibit troff error messages; implies -Ww. This option does not
80 suppress messages sent to the standard error stream by documents
81 or macro packages using tm or related requests.
82 -f fam Use fam as the default font family.
84 -F dir Search in directory dir for the selected output device's direc‐
86 tory of device and font description files. See the description
87 of GROFF_FONT_PATH in section “Environment” below for the de‐
88 fault search locations and ordering.
89 -i Read the standard input stream after all named input files have
91 been processed.
92 -I dir Search the directory dir for files (those named on the command
94 line; in psbb, so, and soquiet requests; and in “\X'ps: im‐
95 port'”, “\X'ps: file'”, and “\X'pdf: pdfpic'” device control es‐
96 cape sequences). -I may be specified more than once; each dir
97 is searched in the given order. To search the current working
98 directory before others, add “-I .” at the desired place; it is
99 otherwise searched last. -I works similarly to, and is named
100 for, the “include” option of Unix C compilers.
101 -m name
103 Process the file name.tmac prior to any input files. If not
104 found, tmac.name is attempted. name (in both arrangements) is
105 presumed to be a macro file; see the description of
106 GROFF_TMAC_PATH in section “Environment” below for the default
107 search locations and ordering.
108 -M dir Search directory dir for macro files. See the description of
110 GROFF_TMAC_PATH in section “Environment” below for the default
111 search locations and ordering.
112 -n num Begin numbering pages at num. The default is 1.
114 -o list
116 Output only pages in list, which is a comma-separated list of
117 inclusive page ranges; n means page n, m-n means every page be‐
118 tween m and n, -n means every page up to n, and n- means every
119 page from n on. troff stops processing and exits after format‐
120 ting the last page enumerated in list.
121 -r cnumeric-expression
123 -r register=numeric-expression
124 Define roff register c or register as numeric-expression.
125 c must be a one-character name; register can be of arbitrary
126 length. Such register assignments happen before any macro file
127 is loaded, including the startup file. Due to getopt_long(3)
128 limitations, c cannot be, and register cannot contain, an equals
129 sign, even though that is a valid character in a roff identi‐
130 fier.
131 -R Don't load troffrc and troffrc-end.
133 -T dev Prepare output for device dev. The default is ps; see groff(1).
135 -U Operate in unsafe mode, enabling the open, opena, pi, pso, and
137 sy requests, which are disabled by default because they allow an
138 untrusted input document to write to arbitrary file names and
139 run arbitrary commands. This option also adds the current di‐
140 rectory to the macro package search path; see the -m and -M op‐
141 tions above.
142 -w name
144 -W name
145 Enable (-w) or inhibit (-W) warnings in category name. See sec‐
146 tion “Warnings” below.
147 -z Suppress formatted output.
149
151 Warning diagnostics emitted by troff are divided into named, numbered
152 categories. The name associated with each warning category is used by
153 the -w and -W options. Each category is also assigned a power of two;
154 the sum of enabled category codes is used by the warn request and the
155 .warn register. Warnings of each category are produced under the fol‐
156 lowing circumstances.
157 ┌──────────────────────┬─────────────────────────────┐
159 │Bit Code Category │ Bit Code Category │
160 ├──────────────────────┼─────────────────────────────┤
161 │ 0 1 char │ 10 1024 reg │
162 │ 1 2 number │ 11 2048 tab │
163 │ 2 4 break │ 12 4096 right-brace │
164 │ 3 8 delim │ 13 8192 missing │
165 │ 4 16 el │ 14 16384 input │
166 │ 5 32 scale │ 15 32768 escape │
167 │ 6 64 range │ 16 65536 space │
168 │ 7 128 syntax │ 17 131072 font │
169 │ 8 256 di │ 18 262144 ig │
170 │ 9 512 mac │ 19 524288 color │
171 │ │ 20 1048576 file │
172 └──────────────────────┴─────────────────────────────┘
173 break 4 A filled output line could not be broken such that
174 its length was less than the output line length
175 \n[.l]. This category is enabled by default.
176 char 1 No mounted font defines a glyph for the requested
178 character. This category is enabled by default.
179 color 524288 An undefined color name was selected, an attempt
181 was made to define a color using an unrecognized
182 color space, an invalid component in a color defi‐
183 nition was encountered, or an attempt was made to
184 redefine a default color.
185 delim 8 The closing delimiter in an escape sequence was
187 missing or mismatched.
188 di 256 A di, da, box, or boxa request was invoked without
190 an argument when there was no current diversion.
191 el 16 The el request was encountered with no prior corre‐
193 sponding ie request.
194 escape 32768 An unsupported escape sequence was encountered.
196 file 1048576 An attempt was made to load a file that does not
198 exist. This category is enabled by default.
199 font 131072 A non-existent font was selected, or the selection
201 was ignored because a font selection escape se‐
202 quence was used after the output line continuation
203 escape sequence on an input line. This category is
204 enabled by default.
205 ig 262144 An invalid escape sequence occurred in input ig‐
207 nored using the ig request. This warning category
208 diagnoses a condition that is an error when it oc‐
209 curs in non-ignored input.
210 input 16384 An invalid character occurred on the input stream.
212 mac 512 An undefined string, macro, or diversion was used.
214 When such an object is dereferenced, an empty one
215 of that name is automatically created. So, unless
216 it is later deleted, at most one warning is given
217 for each.
218 This warning is also emitted upon an attempt to
220 move an unplanted trap macro. In such cases, the
221 unplanted macro is not dereferenced, so it is not
222 created if it does not exist.
223 missing 8192 A request was invoked with a mandatory argument ab‐
225 sent.
226 number 2 An invalid numeric expression was encountered.
228 This category is enabled by default.
229 range 64 A numeric expression was out of range for its con‐
231 text.
232 reg 1024 An undefined register was used. When an undefined
234 register is dereferenced, it is automatically de‐
235 fined with a value of 0. So, unless it is later
236 deleted, at most one warning is given for each.
237 right-brace 4096 A right brace escape sequence \} was encountered
239 where a number was expected.
240 scale 32 A scaling unit inappropriate to its context was
242 used in a numeric expression.
243 space 65536 A space was missing between a request or macro and
245 its argument. This warning is produced when an un‐
246 defined name longer than two characters is encoun‐
247 tered and the first two characters of the name con‐
248 stitute a defined name. No request is invoked, no
249 macro called, and an empty macro is not defined.
250 This category is enabled by default. It never oc‐
251 curs in compatibility mode.
252 syntax 128 A self-contradictory hyphenation mode was re‐
254 quested; an empty or incomplete numeric expression
255 was encountered; an operand to a numeric operator
256 was missing; an attempt was made to define a recur‐
257 sive, empty, or nonsensical character class; or a
258 groff extension conditional expression operator was
259 used while in compatibility mode.
260 tab 2048 A tab character was encountered where a number was
262 expected, or appeared in an unquoted macro argu‐
263 ment.
264 Two warning names group other warning categories for convenience.
266 all All warning categories except di, mac, and reg. This shorthand
268 is intended to produce all warnings that are useful with macro
269 packages and documents written for AT&T troff and its descen‐
270 dants, which have less fastidious diagnostics than GNU troff.
271 w All warning categories. Authors of documents and macro packages
273 targeting groff are encouraged to use this setting.
274
276 GROFF_FONT_PATH and GROFF_TMAC_PATH each accept a search path of direc‐
277 tories; that is, a list of directory names separated by the system's
278 path component separator character. On Unix systems, this character is
279 a colon (:); on Windows systems, it is a semicolon (;).
280 GROFF_FONT_PATH
282 A list of directories in which to seek the selected output de‐
283 vice's directory of device and font description files. troff
284 will scan directories given as arguments to any specified -F op‐
285 tions before these, then in a site-specific directory (/etc/
286 groff/site-font), a standard location (/usr/share/groff/1.23.0/
287 font), and a compatibility directory (/usr/lib/font) after them.
288 GROFF_TMAC_PATH
290 A list of directories in which to search for macro files. troff
291 will scan directories given as arguments to any specified -M op‐
292 tions before these, then the current directory (only if in un‐
293 safe mode), the user's home directory, a site-specific directory
294 (/etc/groff/site-tmac), and a standard location (/usr/share/
295 groff/1.23.0/tmac) after them.
296 GROFF_TYPESETTER
298 Set the default output device. If empty or not set, ps is used.
299 The -T option overrides GROFF_TYPESETTER.
300 SOURCE_DATE_EPOCH
302 A timestamp (expressed as seconds since the Unix epoch) to use
303 as the output creation timestamp in place of the current time.
304 The time is converted to human-readable form using localtime(3)
305 when the formatter starts up and stored in registers usable by
306 documents and macro packages.
307 TZ The timezone to use when converting the current time (or value
309 of SOURCE_DATE_EPOCH) to human-readable form; see tzset(3).
310
312 /usr/share/groff/1.23.0/tmac/troffrc
313 is an initialization macro file loaded before any macro packages
314 specified with -m options.
315 /usr/share/groff/1.23.0/tmac/troffrc-end
317 is an initialization macro file loaded after all macro packages
318 specified with -m options.
319 /usr/share/groff/1.23.0/tmac/name.tmac
321 are macro files distributed with groff.
322 /usr/share/groff/1.23.0/font/devname/DESC
324 describes the output device name.
325 /usr/share/groff/1.23.0/font/devname/F
327 describes the font F of device name.
328 troffrc and troffrc-end are sought neither in the current nor the home
330 directory by default for security reasons, even if the -U option is
331 specified. Use the -M command-line option or the GROFF_TMAC_PATH envi‐
332 ronment variable to add these directories to the search path if neces‐
333 sary.
334
336 The GNU version of troff was originally written by James Clark; he also
337 wrote the original version of this document, which was updated by
338 Werner Lemberg ⟨wl@gnu.org⟩, Bernd Warken ⟨groff-bernd.warken-72@web
339 .de⟩, and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩.
340
342 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
343 Lemberg, is the primary groff manual. You can browse it interactively
344 with “info groff”.
345 groff(1)
347 offers an overview of the GNU roff system and describes its
348 front end executable.
349 groff(7)
351 details the groff language, including a short but complete ref‐
352 erence of all predefined requests, registers, and escape se‐
353 quences.
354 groff_char(7)
356 explains the syntax of groff special character escape sequences,
357 and lists all special characters predefined by the language.
358 groff_diff(7)
360 enumerates the differences between AT&T device-independent troff
361 and groff.
362 groff_font(5)
364 covers the format of groff device and font description files.
365 groff_out(5)
367 describes the format of troff's output.
368 groff_tmac(5)
370 includes information about macro files that ship with groff.
371 roff(7)
373 supplies background on roff systems in general, including point‐
374 ers to further related documentation.
375groff 1.23.0 2 November 2023 troff(1)