1TROFF(1) General Commands Manual TROFF(1)
2
6 troff - the troff processor of the groff text formatting system
7
9 troff [-abcivzCERU] [-d cs] [-f fam] [-F dir] [-I dir] [-m name]
10 [-M dir] [-n num] [-o list] [-r cn] [-T name] [-w name] [-W name]
11 [file ...]
12
14 This manual page describes the GNU version of troff. It is part of the
15 groff document formatting system. It is functionally compatible with
16 Unix troff, but has many extensions, see groff_diff(7). Usually it
17 should be invoked using the groff(1) command which will also run pre‐
18 processors and postprocessors in the appropriate order and with the ap‐
19 propriate options.
20
22 Whitespace is permitted between a command-line option and its argument.
23 -a Generate an ASCII approximation of the typeset output.
25 -b Print a backtrace with each warning or error message. This
27 backtrace should help track down the cause of the error. The
28 line numbers given in the backtrace may not always be correct,
29 for troff's idea of line numbers gets confused by as or am re‐
30 quests.
31 -c Disable color output (always disabled in compatibility mode).
33 -C Enable compatibility mode.
35 -dcs
37 -dname=s
38 Define c or name to be a string s; c must be a one letter name.
39 -E Inhibit all error messages of troff. Note that this doesn't af‐
41 fect messages output to standard error by macro packages using
42 the tm or tm1 requests.
43 -ffam Use fam as the default font family.
45 -Fdir Search in directory (or directory path) dir for subdirectories
47 devname (name is the name of the device) and there for the DESC
48 file and font files. dir is scanned before all other font di‐
49 rectories.
50 -i Read the standard input after all the named input files have
52 been processed.
53 -Idir This option may be used to add a directory to the search path
55 for files (both those on the command line and those named in
56 .psbb requests). The search path is initialized with the cur‐
57 rent directory. This option may be specified more than once;
58 the directories are then searched in the order specified (but
59 before the current directory). If you want to make the current
60 directory be read before other directories, add -I. at the ap‐
61 propriate place.
62 No directory search is performed for files with an absolute file
64 name.
65 -mname Read in the file name.tmac. If it isn't found, try tmac.name
67 instead. It will be first searched for in directories given
68 with the -M command-line option, then in directories given in
69 the GROFF_TMAC_PATH environment variable, then in the current
70 directory (only if in unsafe mode), the home directory, /etc/
71 groff/site-tmac, /etc/groff/site-tmac, and /usr/share/groff/
72 1.22.4/tmac.
73 -Mdir Search directory (or directory path) dir for macro files. This
75 is scanned before all other macro directories.
76 -nnum Number the first page num.
78 -olist Output only pages in list, which is a comma-separated list of
80 page ranges; n means print page n, m-n means print every page
81 between m and n, -n means print every page up to n, n- means
82 print every page from n. troff will exit after printing the
83 last page in the list.
84 -rcn
86 -rname=n
87 Set number register c or name to n; c must be a one character
88 name; n can be any troff numeric expression.
89 -R Don't load troffrc and troffrc-end.
91 -Tname Prepare output for device name, rather than the default ps; see
93 groff(1) for a more detailed description.
94 -U Unsafe mode. This will enable the following requests: open,
96 opena, pso, sy, and pi. For security reasons, these potentially
97 dangerous requests are disabled otherwise. It will also add the
98 current directory to the macro search path.
99 -v Print the version number.
101 -wname Enable warning name. Available warnings are described in sec‐
103 tion “Warnings” below. To enable most useful warnings use -w
104 all. To enable absolutely all warnings use -w w instead. Mul‐
105 tiple -w options are allowed.
106 -Wname Inhibit warning name. Multiple -W options are allowed.
108 -z Suppress formatted output.
110
112 The warnings that can be given by troff are divided into the following
113 categories. The name associated with each warning is used by the -w
114 and -W options; the number is used by the warn request, and by the
115 .warn register; it is always a power of 2 to allow bitwise composition.
116 ┌─────────────────────┬─────────────────────────────┐
118 │Bit Code Warning │ Bit Code Warning │
119 ├─────────────────────┼─────────────────────────────┤
120 │ 0 1 char │ 10 1024 reg │
121 │ 1 2 number │ 11 2048 tab │
122 │ 2 4 break │ 12 4096 right-brace │
123 │ 3 8 delim │ 13 8192 missing │
124 │ 4 16 el │ 14 16384 input │
125 │ 5 32 scale │ 15 32768 escape │
126 │ 6 64 range │ 16 65536 space │
127 │ 7 128 syntax │ 17 131072 font │
128 │ 8 256 di │ 18 262144 ig │
129 │ 9 512 mac │ 19 524288 color │
130 │ │ 20 1048576 file │
131 └─────────────────────┴─────────────────────────────┘
132 break 4 In fill mode, lines which could not be broken so
133 that their length was less than the line length.
134 This is enabled by default.
135 char 1 Non-existent characters. This is enabled by de‐
137 fault.
138 color 524288 Color-related warnings.
140 delim 8 Missing or mismatched closing delimiters.
142 di 256 Use of di or da without an argument when there is
144 no current diversion.
145 el 16 Use of the el request with no matching ie request.
147 escape 32768 Unrecognized escape sequences. When an unrecog‐
149 nized escape sequence is encountered, the escape
150 character is ignored.
151 file 1048576 Indicates a missing file for the mso request. En‐
153 abled by default.
154 font 131072 Non-existent fonts. This is enabled by default.
156 ig 262144 Invalid escapes in text ignored with the ig re‐
158 quest. These are conditions that are errors when
159 they do not occur in ignored text.
160 input 16384 Invalid input characters.
162 mac 512 Use of undefined strings, macros and diversions.
164 When an undefined string, macro or diversion is
165 used, that string is automatically defined as
166 empty. So, in most cases, at most one warning will
167 be given for each name.
168 missing 8192 Requests that are missing non-optional arguments.
170 number 2 Invalid numeric expressions. This is enabled by
172 default.
173 range 64 Out of range arguments.
175 reg 1024 Use of undefined number registers. When an unde‐
177 fined number register is used, that register is au‐
178 tomatically defined to have a value of 0. So, in
179 most cases, at most one warning will be given for
180 use of a particular name.
181 right-brace 4096 Use of \} where a number was expected.
183 scale 32 Meaningless scaling indicators.
185 space 65536 Missing space between a request or macro and its
187 argument. This warning will be given when an unde‐
188 fined name longer than two characters is encoun‐
189 tered, and the first two characters of the name
190 make a defined name. The request or macro will not
191 be invoked. When this warning is given, no macro
192 is automatically defined. This is enabled by de‐
193 fault. This warning will never occur in compati‐
194 bility mode.
195 syntax 128 Dubious syntax in numeric expressions.
197 tab 2048 Inappropriate use of a tab character. Either use
199 of a tab character where a number was expected, or
200 use of tab character in an unquoted macro argument.
201 There are also names that can be used to refer to groups of warnings:
203 all All warnings except di, mac, and reg. It is intended that this
205 covers all warnings that are useful with traditional macro pack‐
206 ages.
207 w All warnings.
209
211 GROFF_TMAC_PATH
212 A colon separated list of directories in which to search for
213 macro files. troff will scan directories given in the -M option
214 before these, and in standard directories (current directory if
215 in unsafe mode, home directory, /etc/groff/site-tmac, /etc/
216 groff/site-tmac, /usr/share/groff/1.22.4/tmac) after these.
217 GROFF_TYPESETTER
219 Default device.
220 GROFF_FONT_PATH
222 A colon separated list of directories in which to search for the
223 devname directory. troff will scan directories given in the -F
224 option before these, and in standard directories (/etc/groff/
225 site-font, /usr/share/groff/1.22.4/font, /usr/lib/font) after
226 these.
227
229 /usr/share/groff/1.22.4/tmac/troffrc
230 Initialization file (called before any other macro package).
231 /usr/share/groff/1.22.4/tmac/troffrc-end
233 Initialization file (called after any other macro package).
234 /usr/share/groff/1.22.4/tmac/name.tmac
236 /usr/share/groff/1.22.4/tmac/tmac.name
237 Macro files
238 /usr/share/groff/1.22.4/font/devname/DESC
240 Device description file for device name.
241 /usr/share/groff/1.22.4/font/devname/F
243 Font file for font F of device name.
244 Note that troffrc and troffrc-end are searched for neither in the cur‐
246 rent nor the home directory by default for security reasons (even if
247 the -U option is given). Use the -M command-line option or the
248 GROFF_TMAC_PATH environment variable to add these directories to the
249 search path if necessary.
250
252 The GNU version of troff was originally written by James Clark; he also
253 wrote the original version of this document, which was modified by
254 Werner Lemberg ⟨wl@gnu.org⟩ and Bernd Warken ⟨groff-bernd.warken-72@
255 web.de⟩.
256
258 groff(1)
259 The main program of the groff system, a wrapper around troff.
260 groff(7)
262 A description of the groff language, including a short but com‐
263 plete reference of all predefined requests, registers, and es‐
264 capes of plain groff. From the command line, this is called by
265 man 7 groff
267 groff_diff(7)
269 The differences of the groff language and the classical troff
270 language. Currently, this is the most actual document of the
271 groff system.
272 roff(7)
274 An overview over groff and other roff systems, including point‐
275 ers to further related documentation.
276 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
278 Lemberg, is the primary groff manual. You can browse it interactively
279 with “info groff”.
280groff 1.22.4 19 January 2023 TROFF(1)