Debian Codegraph @

upstream/debian-trixie/man1/nroff.1

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