| blob | 0d6b26ad3ce55998fb8130ef1fbbb0607d09ef29 |
1 '\" t
2 .ig
3 troff.man
5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 1989, 2000, 2001, 2002, 2003, 2007, 2008
8 Free Software Foundation, Inc.
10 written by James Clark
12 modified by Werner Lemberg <wl@gnu.org>
13 Bernd Warken <bwarken@mayn.de>
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.1 or
17 any later version published by the Free Software Foundation; with the
18 Invariant Sections being this .ig-section and AUTHOR, with no
19 Front-Cover Texts, and with no Back-Cover Texts.
21 A copy of the Free Documentation License is included as a file called
22 FDL in the main directory of the groff source package.
23 ..
24 .
25 .\" --------------------------------------------------------------------
26 .\" Title
27 .\" --------------------------------------------------------------------
28 .
29 .TH @G@TROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
30 .SH NAME
31 @g@troff \- the troff processor of the groff text formatting system
32 .
33 .
34 .\" --------------------------------------------------------------------
35 .SH SYNOPSIS
36 .\" --------------------------------------------------------------------
37 .
38 .SY @g@troff
39 .OP \-abcivzCERU
40 .OP \-d cs
41 .OP \-f fam
42 .OP \-F dir
43 .OP \-I dir
44 .OP \-m name
45 .OP \-M dir
46 .OP \-n num
47 .OP \-o list
48 .OP \-r cn
49 .OP \-T name
50 .OP \-w name
51 .OP \-W name
52 .RI "[\ " files\|.\|.\|. "\ ]"
53 .YS
54 .
55 .
56 .\" --------------------------------------------------------------------
57 .SH DESCRIPTION
58 .\" --------------------------------------------------------------------
59 .
60 This manual page describes the GNU version of
61 .BR troff .
62 It is part of the groff document formatting system.
63 .
64 It is functionally compatible with UNIX troff, but has many extensions,
65 see
66 .BR \%groff_diff (@MAN7EXT@).
67 Usually it should be invoked using the
68 .BR groff (@MAN1EXT@)
69 command which will also run preprocessors and postprocessors in the
70 appropriate order and with the appropriate options.
71 .
72 .
73 .\" --------------------------------------------------------------------
74 .SH OPTIONS
75 .\" --------------------------------------------------------------------
76 It is possible to have whitespace between a command line option and
77 its parameter.
78 .
79 .TP \w'\-dname=s'u+2n
80 .B \-a
81 Generate an
82 .SM ASCII
83 approximation of the typeset output.
84 .
85 .TP
86 .B \-b
87 Print a backtrace with each warning or error message.
88 .
89 This backtrace should help track down the cause of the error.
90 .
91 The line numbers given in the backtrace may not always be correct, for
92 .BR @g@troff 's
93 idea of line numbers gets confused by
94 .B as
95 or
96 .B am
97 requests.
98 .
99 .TP
100 .B \-c
101 Disable color output (always disabled in compatibility mode).
102 .
103 .TP
104 .B \-C
105 Enable compatibility mode.
106 .
107 .TP
108 .BI \-d cs
109 .TQ
110 .BI \-d name = s
111 Define
112 .I c
113 or
114 .I name
115 to be a string
116 .IR s ;
117 .I c
118 must be a one letter name.
119 .
120 .TP
121 .B \-E
122 Inhibit all error messages of
123 .BR @g@troff .
124 Note that this doesn't affect messages output to standard error by macro
125 packages using the
126 .B tm
127 or
128 .B tm1
129 requests.
130 .
131 .TP
132 .BI \-f fam
133 Use
134 .I fam
135 as the default font family.
136 .
137 .TP
138 .BI \-F dir
139 Search in directory (or directory path)
140 .I dir
141 for subdirectories
142 .BI dev name
143 .RI ( name
144 is the name of the device) and there for the
145 .B DESC
146 file and font files.
147 .I dir
148 is scanned before all other font directories.
149 .
150 .TP
151 .B \-i
152 Read the standard input after all the named input files have been
153 processed.
154 .
155 .TP
156 .BI \-I dir
157 This option may be used to specify a directory to search for
158 files (both those on the command line and those named in
159 .B \&.psbb
160 requests).
161 The current directory is always searched first.
162 This option may be specified more than once;
163 the directories will be searched in the order specified.
164 No directory search is performed for files specified using an absolute path.
165 .
166 .TP
167 .BI \-m name
168 Read in the file
169 .IB name .tmac\fR.
170 If it isn't found, try
171 .BI tmac. name
172 instead.
173 .
174 It will be first searched for in directories given with the
175 .B \-M
176 command line option, then in directories given in the
177 .B GROFF_TMAC_PATH
178 environment variable, then in the current directory (only if in unsafe
179 mode), the home directory, @SYSTEMMACRODIR@, @LOCALMACRODIR@, and
180 @MACRODIR@.
181 .
182 .TP
183 .BI \-M dir
184 Search directory (or directory path)
185 .I dir
186 for macro files.
187 .
188 This is scanned before all other macro directories.
189 .
190 .TP
191 .BI \-n num
192 Number the first page
193 .IR num .
194 .
195 .TP
196 .BI \-o list
197 Output only pages in
198 .IR list ,
199 which is a comma-separated list of page ranges;
200 .I n
201 means print page
202 .IR n ,
203 .IB m \- n
204 means print every page between
205 .I m
206 and
207 .IR n ,
208 .BI \- n
209 means print every page up to
210 .IR n ,
211 .IB n \-
212 means print every page from
213 .IR n .
214 .B @g@troff
215 will exit after printing the last page in the list.
216 .
217 .TP
218 .BI \-r cn
219 .TQ
220 .BI \-r name = n
221 Set number register
222 .I c
223 or
224 .I name
225 to
226 .IR n ;
227 .I c
228 must be a one character name;
229 .I n
230 can be any troff numeric expression.
231 .
232 .TP
233 .B \-R
234 Don't load
235 .B troffrc
236 and
237 .BR troffrc-end .
238 .
239 .TP
240 .BI \-T name
241 Prepare output for device
242 .IR name ,
243 rather than the default
244 .BR @DEVICE@ ;
245 see
246 .BR groff (@MAN1EXT@)
247 for a more detailed description.
248 .
249 .TP
250 .B \-U
251 Unsafe mode.
252 .
253 This will enable the following requests:
254 .BR open ,
255 .BR opena ,
256 .BR pso ,
257 .BR sy ,
258 and
259 .BR pi .
260 For security reasons, these potentially dangerous requests are disabled
261 otherwise.
262 .
263 It will also add the current directory to the macro search path.
264 .
265 .TP
266 .B \-v
267 Print the version number.
268 .
269 .TP
270 .BI \-w name
271 Enable warning
272 .IR name .
273 Available warnings are described in the section
274 .I WARNINGS
275 below.
276 .
277 For example, to enable all warnings, use
278 .B \-w
279 .BR all .
280 Multiple
281 .B \-w
282 options are allowed.
283 .
284 .TP
285 .BI \-W name
286 Inhibit warning
287 .IR name .
288 Multiple
289 .B \-W
290 options are allowed.
291 .
292 .TP
293 .B \-z
294 Suppress formatted output.
295 .
296 .
297 .\" --------------------------------------------------------------------
298 .SH WARNINGS
299 .\" --------------------------------------------------------------------
300 .
301 The warnings that can be given by
302 .B @g@troff
303 are divided into the following categories.
304 .
305 The name associated with each warning is used by the
306 .B \-w
307 and
308 .B \-W
309 options; the number is used by the
310 .B warn
311 request, and by the
312 .B .warn
313 register; it is always a power of 2 to allow bitwise composition.
314 .
315 .P
316 .TS
317 tab(@), center, box;
318 c c c | c c c
319 r rI lB | r rI lB.
320 Bit@Code@Warning@Bit@Code@Warning
321 _
322 0@1@char@10@1024@reg
323 1@2@number@11@2048@tab
324 2@4@break@12@4096@right-brace
325 3@8@delim@13@8192@missing
326 4@16@el@14@16384@input
327 5@32@scale@15@32768@escape
328 6@64@range@16@65536@space
329 7@128@syntax@17@131072@font
330 8@256@di@18@262144@ig
331 9@512@mac@19@524288@color
332 .TE
333 .
334 .P
335 .nr x \w'\fBright-brace'+1n+\w'00000'u
336 .ta \nxuR
337 .
338 .TP \nxu+3n
339 .BR break "\t4"
340 In fill mode, lines which could not be broken so that their length was
341 less than the line length.
342 .
343 This is enabled by default.
344 .
345 .TP
346 .BR char "\t1"
347 Non-existent characters.
348 .
349 This is enabled by default.
350 .
351 .TP
352 .BR color "\t524288"
353 Color related warnings.
354 .
355 .TP
356 .BR delim "\t8"
357 Missing or mismatched closing delimiters.
358 .
359 .TP
360 .BR di "\t256"
361 Use of
362 .B di
363 or
364 .B da
365 without an argument when there is no current diversion.
366 .
367 .TP
368 .BR el "\t16"
369 Use of the
370 .B el
371 request with no matching
372 .B ie
373 request.
374 .
375 .TP
376 .BR escape "\t32768"
377 Unrecognized escape sequences.
378 .
379 When an unrecognized escape sequence is encountered, the escape
380 character is ignored.
381 .
382 .TP
383 .BR font "\t131072"
384 Non-existent fonts.
385 .
386 This is enabled by default.
387 .
388 .TP
389 .BR ig "\t262144"
390 Invalid escapes in text ignored with the
391 .B ig
392 request.
393 .
394 These are conditions that are errors when they do not occur in ignored
395 text.
396 .
397 .TP
398 .BR input "\t16384"
399 Invalid input characters.
400 .
401 .TP
402 .BR mac "\t512"
403 Use of undefined strings, macros and diversions.
404 .
405 When an undefined string, macro or diversion is used, that string is
406 automatically defined as empty.
407 .
408 So, in most cases, at most one warning will be given for each name.
409 .
410 .TP
411 .BR missing "\t8192"
412 Requests that are missing non-optional arguments.
413 .
414 .TP
415 .BR number "\t2"
416 Invalid numeric expressions.
417 .
418 This is enabled by default.
419 .
420 .TP
421 .BR range "\t64"
422 Out of range arguments.
423 .
424 .TP
425 .BR reg "\t1024"
426 Use of undefined number registers.
427 .
428 When an undefined number register is used, that register is
429 automatically defined to have a value of\~0.
430 .
431 So, in most cases, at most one warning will be given for use of a
432 particular name.
433 .
434 .TP
435 .BR right-brace "\t4096"
436 Use of
437 .B \[rs]}
438 where a number was expected.
439 .
440 .TP
441 .BR scale "\t32"
442 Meaningless scaling indicators.
443 .
444 .TP
445 .BR space "\t65536"
446 Missing space between a request or macro and its argument.
447 .
448 This warning will be given when an undefined name longer than two
449 characters is encountered, and the first two characters of the name
450 make a defined name.
451 .
452 The request or macro will not be invoked.
453 .
454 When this warning is given, no macro is automatically defined.
455 .
456 This is enabled by default.
457 .
458 This warning will never occur in compatibility mode.
459 .
460 .TP
461 .BR syntax "\t128"
462 Dubious syntax in numeric expressions.
463 .
464 .TP
465 .BR tab "\t2048"
466 Inappropriate use of a tab character.
467 Either use of a tab character where a number was expected, or use of tab
468 character in an unquoted macro argument.
469 .
470 .P
471 There are also names that can be used to refer to groups of warnings:
472 .
473 .TP
474 .B all
475 All warnings except
476 .BR di ,
477 .BR mac ,
478 and
479 .BR reg .
480 It is intended that this covers all warnings that are useful with
481 traditional macro packages.
482 .
483 .TP
484 .B w
485 All warnings.
486 .
487 .
488 .\" --------------------------------------------------------------------
489 .SH ENVIRONMENT
490 .\" --------------------------------------------------------------------
491 .
492 .TP
493 .SM
494 .B GROFF_TMAC_PATH
495 A colon separated list of directories in which to search for
496 macro files.
497 .B @g@troff
498 will scan directories given in the
499 .B \-M
500 option before these, and in standard directories (current directory if
501 in unsafe mode, home directory,
502 .BR @SYSTEMMACRODIR@ ,
503 .BR @LOCALMACRODIR@ ,
504 .BR @MACRODIR@ )
505 after these.
506 .
507 .TP
508 .SM
509 .B GROFF_TYPESETTER
510 Default device.
511 .
512 .TP
513 .SM
514 .B GROFF_FONT_PATH
515 A colon separated list of directories in which to search for the
516 .BI dev name
517 directory.
518 .B @g@troff
519 will scan directories given in the
520 .B \-F
521 option before these, and in standard directories
522 .RB ( @LOCALFONTDIR@ ,
523 .BR @FONTDIR@ ,
524 .BR @LEGACYFONTDIR@ )
525 after these.
526 .
527 .
528 .\" --------------------------------------------------------------------
529 .SH FILES
530 .\" --------------------------------------------------------------------
531 .
532 .TP
533 .B @MACRODIR@/troffrc
534 Initialization file (called before any other macro package).
535 .
536 .TP
537 .B @MACRODIR@/troffrc-end
538 Initialization file (called after any other macro package).
539 .
540 .TP
541 .BI @MACRODIR@/ name .tmac
542 .TQ
543 .BI @MACRODIR@/tmac. name
544 Macro files
545 .
546 .TP
547 .BI @FONTDIR@/dev name /DESC
548 Device description file for device
549 .IR name .
550 .
551 .TP
552 .BI @FONTDIR@/dev name / F
553 Font file for font
554 .I F
555 of device
556 .IR name .
557 .P
558 Note that
559 .B troffrc
560 and
561 .B troffrc-end
562 are neither searched in the current nor in the home directory by
563 default for security reasons (even if the
564 .B \-U
565 option is given).
566 .
567 Use the
568 .B \-M
569 command line option or the
570 .B GROFF_TMAC_PATH
571 environment variable to add these directories to the search path if
572 necessary.
573 .
574 .
575 .\" --------------------------------------------------------------------
576 .SH AUTHOR
577 .\" --------------------------------------------------------------------
578 .
579 Copyright (C) 1989, 2001, 2002, 2003, 2007, 2008
580 Free Software Foundation, Inc.
581 .
582 .P
583 This document is distributed under the terms of the FDL (GNU Free
584 Documentation License) version 1.1 or later.
585 .
586 You should have received a copy of the FDL on your system, it is also
587 available on-line at the
588 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
589 GNU copyleft site
590 .UE .
591 This document was written by James Clark, with modifications from
592 .MT wl@gnu.org
593 Werner Lemberg
594 .ME
595 and
596 .MT bwarken@mayn.de
597 Bernd Warken
598 .ME .
599 .
600 .P
601 This document is part of
602 .IR groff ,
603 the GNU roff distribution.
604 .
605 .
606 .\" --------------------------------------------------------------------
607 .SH "SEE ALSO"
608 .\" --------------------------------------------------------------------
609 .
610 .TP
611 .BR groff (@MAN1EXT@)
612 The main program of the
613 .I groff
614 system, a wrapper around
615 .IR @g@troff .
616 .
617 .TP
618 .BR groff (@MAN7EXT@)
619 A description of the
620 .I groff
621 language, including a short but complete reference of all predefined
622 requests, registers, and escapes of plain
623 .IR groff .
624 From the command line, this is called by
625 .RS
626 .IP
627 .B man 7 groff
628 .RE
629 .
630 .TP
631 .BR \%groff_diff (@MAN7EXT@)
632 The differences of the
633 .I groff
634 language and the
635 .I classical troff
636 language.
637 .
638 Currently, this is the most actual document of the
639 .I groff
640 system.
641 .
642 .TP
643 .BR roff (@MAN7EXT@)
644 An overview over
645 .I groff
646 and other
647 .I roff
648 systems, including pointers to further related documentation.
649 .
650 .P
651 The
652 .I groff info
653 .IR file ,
654 cf.\&
655 .BR info (@MAN1EXT@),
656 presents all groff documentation within a single document.
657 .
658 .\" --------------------------------------------------------------------
659 .\" Emacs variables
660 .\" --------------------------------------------------------------------
661 .
662 .\" Local Variables:
663 .\" mode: nroff
664 .\" End: