Debian Codegraph @

upstream/debian-unstable/man1/nroff.1

raw
1 .TH \%nroff 1 "2026-04-22" "groff 1.24.1"
2 .SH Name
3 \%nroff \- format documents with
4 .I groff
5 for terminal (\[lq]TTY\[rq]) devices
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright 1989-2023 Free Software Foundation, Inc.
13 .\" 2018-2024 G. Branden Robinson
14 .\"
15 .\" Permission is granted to make and distribute verbatim copies of this
16 .\" manual provided the copyright notice and this permission notice are
17 .\" preserved on all copies.
18 .\"
19 .\" Permission is granted to copy and distribute modified versions of
20 .\" this manual under the conditions for verbatim copying, provided that
21 .\" the entire resulting derived work is distributed under the terms of
22 .\" a permission notice identical to this one.
23 .\"
24 .\" Permission is granted to copy and distribute translations of this
25 .\" manual into another language, under the above conditions for
26 .\" modified versions, except that this permission notice may be
27 .\" included in translations approved by the Free Software Foundation
28 .\" instead of in the original English.
29 .
30 .
31 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
32 .do nr *groff_nroff_1_man_C \n[.cp]
33 .cp 0
34 .
35 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
36 .nr do-fallback 0
37 .if !\n(.f .nr do-fallback 1 \" mandoc
38 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
39 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
40 .if \n[do-fallback] \{\
41 . de MR
42 . ie \\n(.$=1 \
43 . I \%\\$1
44 . el \
45 . IR \%\\$1 (\\$2)\\$3
46 . .
47 .\}
48 .rr do-fallback
49 .
50 .
51 .\" ====================================================================
52 .SH Synopsis
53 .\" ====================================================================
54 .
55 .SY \%nroff
56 .RB [ \-abcCEhikpRStUVzZ ]
57 .RB [ \-d\~\c
58 .IR ctext ]
59 .RB [ \-d\~\c
60 .IB string =\c
61 .IR text ]
62 .RB [ \-D\~\c
63 .IR fallback-input-encoding ]
64 .RB [ \-I\~\c
65 .IR inclusion-directory ]
66 .RB [ \-K\~\c
67 .IR input-encoding ]
68 .RB [ \-m\~\c
69 .IR macro-package ]
70 .RB [ \-M\~\c
71 .IR macro-directory ]
72 .RB [ \-n\~\c
73 .IR page-number ]
74 .RB [ \-o\~\c
75 .IR page-list ]
76 .RB [ \-P\~\c
77 .IR postprocessor-argument ]
78 .RB [ \-r\~\c
79 .IR cnumeric-expression ]
80 .RB [ \-r\~\c
81 .IB register =\c
82 .IR numeric-expression ]
83 .RB [ \-T\~\c
84 .IR output-device ]
85 .RB [ \-w\~\c
86 .IR warning-category ]
87 .RB [ \-W\~\c
88 .IR warning-category ]
89 .RI [ file\~ .\|.\|.]
90 .YS
91 .
92 .
93 .P
94 .SY \%nroff
95 .B \-\-help
96 .YS
97 .
98 .
99 .P
100 .SY \%nroff
101 .B \-v
102 .RI [ other-nroff-option \~.\|.\|.]
103 .YS
104 .
105 .SY \%nroff
106 .B \%\-\-version
107 .RI [ other-nroff-option \~.\|.\|.]
108 .YS
109 .
110 .
111 .\" ====================================================================
112 .SH Description
113 .\" ====================================================================
114 .
115 .I \%nroff
116 formats documents written in the
117 .MR groff 7
118 language for typewriter-like devices such as terminal emulators.
119 .
120 GNU
121 .I nroff \" GNU
122 emulates the AT&T
123 .I nroff \" AT&T
124 command using
125 .MR groff 1 .
126 .
127 .I \%nroff
128 generates output via
129 .MR grotty 1 ,
130 .IR groff 's
131 terminal output driver,
132 which needs to know the character encoding scheme used by the device.
133 .
134 Consequently,
135 acceptable arguments to the
136 .B \-T
137 option are
138 .BR ascii ,
139 .BR latin1 ,
140 and
141 .BR utf8 ;
142 any others are ignored.
143 .
144 If neither the
145 .I \%GROFF_TYPESETTER
146 environment variable nor the
147 .B \-T
148 command-line option
149 (which overrides the environment variable)
150 specifies a (valid) device,
151 .I \%nroff
152 consults the locale to select an appropriate output device.
153 .
154 It first tries the
155 .MR locale 1
156 program,
157 then checks several locale-related environment variables;
158 see section \[lq]Environment\[rq] below.
159 .
160 If all of the foregoing fail,
161 .I \%nroff
162 assumes
163 .RB \[lq] "\-T ascii" \[rq].
164 .
165 .
166 .P
167 The
168 .BR \-a ,
169 .BR \-b ,
170 .BR \-c ,
171 .BR \-C ,
172 .BR \-d ,
173 .BR \-E ,
174 .BR \-i ,
175 .BR \-I ,
176 .BR \-m ,
177 .BR \-M ,
178 .BR \-n ,
179 .BR \-o ,
180 .BR \-r ,
181 .BR \-U ,
182 .BR \-w ,
183 .BR \-W ,
184 and
185 .B \-z
186 options have the effects described in
187 .MR \%troff 1 .
188 .
189 .B \-c
190 and
191 .B \-h
192 imply
193 .RB \[lq] "\-P \-c" \[rq]
194 and
195 .RB \[lq] "\-P \-h" \[rq],
196 respectively;
197 .B \-c
198 is also meaningful to
199 .I \%troff
200 itself.
201 .
202 Further,
203 GNU
204 .I nroff \" GNU
205 ignores the AT&T
206 .I nroff \" AT&T
207 options
208 .BR \-e ,
209 .BR \-q ,
210 and
211 .BR \-s .
212 .
213 .MR groff 1
214 documents options
215 .BR \-D ,
216 .BR \-k ,
217 .BR \-K ,
218 .BR \-p ,
219 .BR \-P ,
220 .BR \-R ,
221 .BR \-t ,
222 .BR \-S ,
223 and
224 .BR \-Z .
225 .
226 .B \-V
227 causes
228 .I \%nroff
229 to display the constructed
230 .I groff
231 command on the standard output stream,
232 but does not execute it.
233 .
234 .B \-v
235 and
236 .B \%\-\-version
237 show version information about
238 .I \%nroff
239 and the programs it runs,
240 while
241 .B \-\-help
242 displays a usage message;
243 all exit afterward.
244 .
245 .
246 .\" ====================================================================
247 .SH "Exit status"
248 .\" ====================================================================
249 .
250 .I \%nroff
251 exits with
252 .RB status\~ 2
253 if there was a problem parsing its arguments,
254 with
255 .RB status\~ 0
256 if any of the options
257 .BR \-V ,
258 .BR \-v ,
259 .BR \%\-\-version ,
260 or
261 .B \-\-help
262 were specified,
263 and with the status of
264 .I groff
265 otherwise.
266 .
267 .
268 .\" ====================================================================
269 .SH Environment
270 .\" ====================================================================
271 .
272 Normally,
273 the path separator in environment variables ending with
274 .I PATH
275 is the colon;
276 this may vary depending on the operating system.
277 .
278 For example,
279 Windows uses a semicolon instead.
280 .
281 .
282 .TP
283 .I GROFF_BIN_PATH
284 Locate
285 .I groff \" system
286 commands
287 in these directories,
288 followed by those in
289 .IR PATH .
290 .
291 If not set,
292 the installation directory of GNU
293 .I roff
294 executables,
295 .IR /usr/\:\%bin ,
296 is searched before
297 .IR PATH .
298 .
299 .
300 .TP
301 .I GROFF_TYPESETTER
302 specifies the default output device for
303 .IR groff .
304 .
305 .
306 .TP
307 .I LC_ALL
308 .TQ
309 .I LC_CTYPE
310 .TQ
311 .I LANG
312 .TQ
313 .I LESSCHARSET
314 are pattern-matched in this order for contents matching standard
315 character encodings supported by
316 .I groff
317 in the event no
318 .B \-T
319 option is given and
320 .I \%GROFF_TYPESETTER
321 is unset,
322 or the values specified are invalid.
323 .
324 .
325 .\" ====================================================================
326 .SH Files
327 .\" ====================================================================
328 .
329 .TP
330 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:\%tty\-char\:.tmac
331 defines fallback definitions of
332 .I roff
333 special characters.
334 .
335 These definitions more poorly optically approximate typeset output
336 than those of
337 .I tty.tmac
338 in favor of communicating semantic information.
339 .
340 .I nroff
341 loads it automatically.
342 .
343 .
344 .\" ====================================================================
345 .SH Notes
346 .\" ====================================================================
347 .
348 Pager programs like
349 .MR more 1
350 and
351 .MR less 1
352 may require command-line options to correctly handle some output
353 sequences;
354 see
355 .MR grotty 1 .
356 .
357 .
358 .\" ====================================================================
359 .SH "See also"
360 .\" ====================================================================
361 .
362 .MR groff 1 ,
363 .MR \%troff 1 ,
364 .MR grotty 1 ,
365 .MR locale 1 ,
366 .MR roff 7
367 .
368 .
369 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
370 .cp \n[*groff_nroff_1_man_C]
371 .do rr *groff_nroff_1_man_C
372 .
373 .
374 .\" Local Variables:
375 .\" fill-column: 72
376 .\" mode: nroff
377 .\" End:
378 .\" vim: set filetype=groff textwidth=72: