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