5 Last update : 9 Jan 2002
7 This file is part of groff, the GNU roff type-setting system.
9 Copyright (C) 1989, 2000, 2001, 2002 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.
27 .\" --------------------------------------------------------------------
29 .\" --------------------------------------------------------------------
49 .\" Like TP, but if specified indent is more than half
50 .\" the current line-length - indent, use the default indent.
52 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
57 .\" --------------------------------------------------------------------
59 .\" --------------------------------------------------------------------
61 .TH @G@TROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
63 @g@troff \- the troff processor of the groff text formatting system
66 .\" --------------------------------------------------------------------
68 .\" --------------------------------------------------------------------
73 .in +\w'\fB@g@troff 'u
77 .ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
78 .el .RB "[\ " "\\$1" "\ ]"
92 .RI "[\ " files\|.\|.\|. "\ ]"
96 It is possible to have whitespace between a command line option and
100 .\" --------------------------------------------------------------------
102 .\" --------------------------------------------------------------------
104 This manual page describes the GNU version of
106 It is part of the groff document formatting system.
108 It is functionally compatible with UNIX troff, but has many extensions,
110 .BR \%groff_diff (@MAN7EXT@).
111 Usually it should be invoked using the
112 .BR groff (@MAN1EXT@)
113 command which will also run preprocessors and postprocessors in the
114 appropriate order and with the appropriate options.
117 .\" --------------------------------------------------------------------
119 .\" --------------------------------------------------------------------
121 .TP \w'\-dname=s'u+2n
125 approximation of the typeset output.
129 Print a backtrace with each warning or error message.
131 This backtrace should help track down the cause of the error.
133 The line numbers given in the backtrace may not always be correct, for
135 idea of line numbers gets confused by
143 Disable color output (always disabled in compatibility mode).
147 Enable compatibility mode.
160 must be a one letter name.
164 Inhibit all error messages of
166 Note that this doesn't affect messages output to standard error by macro
177 as the default font family.
181 Search in directory (or directory path)
186 is the name of the device) and there for the
190 is scanned before all other font directories.
194 Read the standard input after all the named input files have been
201 If it isn't found, try
205 It will be first searched for in directories given with the
207 command line option, then in directories given in the
209 environment variable, then in the current directory (only if in unsafe
210 mode), the home directory, @SYSTEMMACRODIR@, @LOCALMACRODIR@, and
215 Search directory (or directory path)
219 This is scanned before all other macro directories.
223 Number the first page
230 which is a comma-separated list of page ranges;
235 means print every page between
240 means print every page up to
243 means print every page from
246 will exit after printing the last page in the list.
259 must be a one character name;
261 can be any troff numeric expression.
272 Prepare output for device
274 rather than the default
281 This will enable the following requests:
288 For security reasons, these potentially dangerous requests are disabled
291 It will also add the current directory to the macro search path.
295 Print the version number.
301 Available warnings are described in the section
305 For example, to enable all warnings, use
322 Suppress formatted output.
325 .\" --------------------------------------------------------------------
327 .\" --------------------------------------------------------------------
329 The warnings that can be given by
331 are divided into the following categories.
333 The name associated with each warning is used by the
337 options; the number is used by the
341 register; it is always a power of 2 to allow bitwise composition.
348 Bit@Code@Warning@Bit@Code@Warning
351 1@2@number@11@2048@tab
352 2@4@break@12@4096@right-brace
353 3@8@delim@13@8192@missing
354 4@16@el@14@16384@input
355 5@32@scale@15@32768@escape
356 6@64@range@16@65536@space
357 7@128@syntax@17@131072@font
358 8@256@di@18@262144@ig
359 9@512@mac@19@524288@color
363 .nr x \w'\fBright-brace'+1n+\w'00000'u
368 In fill mode, lines which could not be broken so that their length was
369 less than the line length.
371 This is enabled by default.
375 Non-existent characters.
377 This is enabled by default.
381 Color related warnings.
385 Missing or mismatched closing delimiters.
393 without an argument when there is no current diversion.
399 request with no matching
405 Unrecognized escape sequences.
407 When an unrecognized escape sequence is encountered, the escape
408 character is ignored.
414 This is enabled by default.
418 Invalid escapes in text ignored with the
422 These are conditions that are errors when they do not occur in ignored
427 Invalid input characters.
431 Use of undefined strings, macros and diversions.
433 When an undefined string, macro or diversion is used, that string is
434 automatically defined as empty.
436 So, in most cases, at most one warning will be given for each name.
440 Requests that are missing non-optional arguments.
444 Invalid numeric expressions.
446 This is enabled by default.
450 Out of range arguments.
454 Use of undefined number registers.
456 When an undefined number register is used, that register is
457 automatically defined to have a value of\~0.
459 So, in most cases, at most one warning will be given for use of a
463 .BR right-brace "\t4096"
466 where a number was expected.
470 Meaningless scaling indicators.
474 Missing space between a request or macro and its argument.
476 This warning will be given when an undefined name longer than two
477 characters is encountered, and the first two characters of the name
480 The request or macro will not be invoked.
482 When this warning is given, no macro is automatically defined.
484 This is enabled by default.
486 This warning will never occur in compatibility mode.
490 Dubious syntax in numeric expressions.
494 Inappropriate use of a tab character.
495 Either use of a tab character where a number was expected, or use of tab
496 character in an unquoted macro argument.
499 There are also names that can be used to refer to groups of warnings:
508 It is intended that this covers all warnings that are useful with
509 traditional macro packages.
516 .\" --------------------------------------------------------------------
518 .\" --------------------------------------------------------------------
523 A colon separated list of directories in which to search for
526 will scan directories given in the
528 option before these, and in standard directories (current directory if
529 in unsafe mode, home directory,
530 .BR @SYSTEMMACRODIR@ ,
531 .BR @LOCALMACRODIR@ ,
543 A colon separated list of directories in which to search for the
547 will scan directories given in the
549 option before these, and in standard directories
554 .\" --------------------------------------------------------------------
556 .\" --------------------------------------------------------------------
558 .Tp \w'@FONTDIR@/devname/DESC'u+3n
559 .B @MACRODIR@/troffrc
560 Initialization file (called before any other macro package).
563 .B @MACRODIR@/troffrc-end
564 Initialization file (called after any other macro package).
567 .BI @MACRODIR@/ name .tmac
569 .BI @MACRODIR@/tmac. name
573 .BI @FONTDIR@/dev name /DESC
574 Device description file for device
578 .BI @FONTDIR@/dev name / F
588 are neither searched in the current nor in the home directory by
589 default for security reasons (even if the
595 command line option or the
597 environment variable to add these directories to the search path if
601 .\" --------------------------------------------------------------------
603 .\" --------------------------------------------------------------------
605 Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc.
608 This document is distributed under the terms of the FDL (GNU Free
609 Documentation License) version 1.1 or later.
611 You should have received a copy of the FDL on your system, it is also
612 available on-line at the
613 .URL http://www.gnu.org/copyleft/fdl.html "GNU copyleft site" .
614 This document was written by James Clark, with modifications from
615 .MTO wl@gnu.org "Werner Lemberg"
617 .MTO bwarken@mayn.de "Bernd Warken"
620 This document is part of
622 the GNU roff distribution.
625 .\" --------------------------------------------------------------------
627 .\" --------------------------------------------------------------------
630 .BR groff (@MAN1EXT@)
631 The main program of the
633 system, a wrapper around
637 .BR groff (@MAN7EXT@)
640 language, including a short but complete reference of all predefined
641 requests, registers, and escapes of plain
643 From the command line, this is called by
650 .BR \%groff_diff (@MAN7EXT@)
651 The differences of the
657 Currently, this is the most actual document of the
667 systems, including pointers to further related documentation.
674 .BR info (@MAN1EXT@),
675 presents all groff documentation within a single document.
678 .\" --------------------------------------------------------------------
680 .\" --------------------------------------------------------------------