1 This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.
3 This manual documents GNU `troff' version 1.18.
5 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
7 Permission is granted to copy, distribute and/or modify this
8 document under the terms of the GNU Free Documentation License,
9 Version 1.1 or any later version published by the Free Software
10 Foundation; with no Invariant Sections, with the Front-Cover texts
11 being `A GNU Manual," and with the Back-Cover Texts as in (a)
12 below. A copy of the license is included in the section entitled
13 `GNU Free Documentation License."
15 (a) The FSF's Back-Cover Text is: `You have freedom to copy and
16 modify this GNU Manual, like GNU software. Copies published by
17 the Free Software Foundation raise funds for GNU development."
19 INFO-DIR-SECTION Miscellaneous
21 * Groff: (groff). The GNU troff document formatting system.
25 File: groff, Node: Diversions, Next: Environments, Prev: Traps, Up: gtroff Reference
30 In `gtroff' it is possible to "divert" text into a named storage
31 area. Due to the similarity to defining macros it is sometimes said to
32 be stored in a macro. This is used for saving text for output at a
33 later time, which is useful for keeping blocks of text on the same
34 page, footnotes, tables of contents, and indices.
36 For orthogonality it is said that `gtroff' is in the "top-level
37 diversion" if no diversion is active (i.e., the data is diverted to the
42 Begin a diversion. Like the `de' request, it takes an argument of
43 a macro name to divert subsequent text into. The `da' macro
44 appends to an existing diversion.
46 `di' or `da' without an argument ends the diversion.
49 - Request: .boxa macro
50 Begin (or appends to) a diversion like the `di' and `da' requests.
51 The difference is that `box' and `boxa' do not include a
52 partially-filled line in the diversion.
64 => Before the box. After the box.
78 => After the diversion.
80 => Before the diversion. In the diversion.
82 `box' or `boxa' without an argument ends the diversion.
86 Diversions may be nested. The read-only number register `.z'
87 contains the name of the current diversion (this is a string-valued
88 register). The read-only number register `.d' contains the current
89 vertical place in the diversion. If not in a diversion it is the
90 same as the register `nl'.
93 The "high-water mark" on the current page. It corresponds to the
94 text baseline of the lowest line on the page. This is a read-only
98 .tm .h==\n[.h], nl==\n[nl]
103 .tm .h==\n[.h], nl==\n[nl]
106 As can be seen in the previous example, empty lines are not
107 considered in the return value of the `.h' register.
111 After completing a diversion, the read-write number registers `dn'
112 and `dl' contain the vertical and horizontal size of the diversion.
115 .\" Center text both horizontally & vertically
117 .\" Enclose macro definitions in .eo and .ec
118 .\" to avoid the doubling of the backslash
120 .\" macro .(c starts centering mode
131 .\" macro .)c terminates centering mode
136 . nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
148 .\" End of macro definitions, restore escape mechanism
153 - Escape: \?ANYTHING\?
154 Prevent requests, macros, and escapes from being interpreted when
155 read into a diversion. This takes the given text and
156 "transparently" embeds it into the diversion. This is useful for
157 macros which shouldn't be invoked until the diverted text is
160 The `\!' escape transparently embeds text up to and including the
161 end of the line. The `\?' escape transparently embeds text until
162 the next occurrence of the `\?' escape. For example:
167 ANYTHING may not contain newlines; use `\!' to embed newlines in
168 a diversion. The escape sequence `\?' is also recognized in copy
169 mode and turned into a single internal code; it is this code that
170 terminates ANYTHING. Thus the following example prints 4.
176 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
189 Both escapes read the data in copy mode.
191 If `\!' is used in the top-level diversion, its argument is
192 directly embedded into the `gtroff' intermediate output. This can
193 be used for example to control a postprocessor which processes the
194 data before it is sent to the device driver.
196 The `\?' escape used in the top-level diversion produces no output
197 at all; its argument is simply ignored.
199 - Request: .output string
200 Emit STRING directly to the `gtroff' intermediate output (subject
201 to copy-mode interpretation); this is similar to `\!' used at the
202 top level. An initial double quote in STRING is stripped off to
203 allow initial blanks.
205 This request can't be used before the first page has started - if
206 you get an error, simply insert `.br' before the `output' request.
208 Without argument, `output' is ignored.
210 Use with caution! It is normally only needed for mark-up used by a
211 postprocessor which does something with the output before sending
212 it to the output device, filtering out `string' again.
214 - Request: .asciify div
215 "Unformat" the diversion specified by DIV in such a way that ASCII
216 characters, characters translated with the `trin' request, space
217 characters, and some escape sequences that were formatted and
218 diverted are treated like ordinary input characters when the
219 diversion is reread. It can be also used for gross hacks; for
220 example, the following sets register `n' to 1.
232 *Note Copy-in Mode::.
234 - Request: .unformat div
235 Like `asciify', unformat the specified diversion. However,
236 `unformat' only unformats spaces and tabs between words.
237 Unformatted tabs are treated as input tokens, and spaces are
240 The vertical size of lines is not preserved; glyph information
241 (font, font size, space width, etc.) is retained.
244 File: groff, Node: Environments, Next: Suppressing output, Prev: Diversions, Up: gtroff Reference
249 It happens frequently that some text should be printed in a certain
250 format regardless of what may be in effect at the time, for example, in
251 a trap invoked macro to print headers and footers. To solve this
252 `gtroff' processes text in "environments". An environment contains
253 most of the parameters that control text processing. It is possible to
254 switch amongst these environments; by default `gtroff' processes text
255 in environment 0. The following is the information kept in an
258 * font parameters (size, family, style, glyph height and slant, space
259 and sentence space size)
261 * page parameters (line length, title length, vertical spacing, line
262 spacing, indentation, line numbering, centering, right-justifying,
263 underlining, hyphenation data)
265 * fill and adjust mode
267 * tab stops, tab and leader characters, escape character, no-break
268 and hyphen indicators, margin character data
270 * partially collected lines
274 * drawing and fill colours
276 These environments may be given arbitrary names (see *Note
277 Identifiers::, for more info). Old versions of `troff' only had
278 environments named `0', `1', and `2'.
282 Switch to another environment. The argument ENV is the name of
283 the environment to switch to. With no argument, `gtroff' switches
284 back to the previous environment. There is no limit on the number
285 of named environments; they are created the first time that they
286 are referenced. The `.ev' read-only register contains the name or
287 number of the current environment. This is a string-valued
290 Note that a call to `ev' (with argument) pushes the previously
291 active environment onto a stack. If, say, environments `foo',
292 `bar', and `zap' are called (in that order), the first `ev'
293 request without parameter switches back to environment `bar'
294 (which is popped off the stack), and a second call switches back
295 to environment `foo'.
310 \(dg Note the large, friendly letters.
315 Copy the environment ENV into the current environment.
317 The following environment data is not copied:
319 * Partially filled lines.
321 * The status whether the previous line was interrupted.
323 * The number of lines still to center, or to right-justify, or
324 to underline (with or without underlined spaces); they are
327 * The status whether a temporary indent is active.
329 * Input traps and its associated data.
331 * Line numbering mode is disabled; it can be reactivated with
334 * The number of consecutive hyphenated lines (set to zero).
339 The `\n[.cht]' register contains the maximum extent (above the
340 baseline) of the last glyph added to the current environment.
342 The `\n[.cdp]' register contains the maximum extent (below the
343 baseline) of the last glyph added to the current environment.
345 The `\n[.csk]' register contains the "skew" (how far to the right
346 of the glyph's center that `gtroff' shold place an accent) of the
347 last glyph added to the current environment.
350 File: groff, Node: Suppressing output, Next: Colors, Prev: Environments, Up: gtroff Reference
356 Disable or enable output depending on the value of NUM:
359 Disable any glyphs from being emitted to the device driver,
360 provided that the escape occurs at the outer level (see
361 `\O[3]' and `\O[4]'). Motion is not suppressed so
362 effectively `\O[0]' means _pen up_.
365 Enable output of glyphs, provided that the escape occurs at
368 `\O0' and `\O1' also reset the four registers `opminx', `opminy',
369 `opmaxx', and `opmaxy' to -1. *Note Register Index::. These four
370 registers mark the top left and bottom right hand corners of a box
371 which encompasses all written glyphs.
373 For example the input text:
376 Hello \O[0]world \O[1]this is a test.
378 produces the following output:
381 Hello this is a test.
384 Provided that the escape occurs at the outer level, enable
385 output of glyphs and also write out to `stderr' the page
386 number and four registers encompassing the glyphs previously
387 written since the last call to `\O'.
390 Begin a nesting level. At start-up, `gtroff' is at outer
397 This escape is `grohtml' specific. Provided that this escape
398 occurs at the outer nesting level write the `filename' to
399 `stderr'. The position of the image, P, must be specified
400 and must be one of `l', `r', `c', or `i' (left, right,
401 centered, inline). FILENAME will be associated with the
402 production of the next inline image.
405 File: groff, Node: Colors, Next: I/O, Prev: Suppressing output, Up: gtroff Reference
410 - Request: .color [n]
411 - Register: \n[.color]
412 If N is missing or non-zero, activate colors (this is the default);
413 otherwise, turn it off.
415 The read-only number register `.color' is 1 if colors are active,
418 Internally, `color' sets a global flag; it does not produce a
419 token. Similar to the `cp' request, you should use it at the
420 beginning of your document to control color output.
422 Colors can be also turned off with the `-c' command line option.
424 - Request: .defcolor ident scheme color_components
425 Define color with name IDENT. SCHEME can be one of the following
426 values: `rgb' (three components), `cym' (three components), `cmyk'
427 (four components), and `gray' or `grey' (one component).
429 Color components can be given either as a hexadecimal string or as
430 positive decimal integers in the range 0-65535. A hexadecimal
431 string contains all color components concatenated. It must start
432 with either `#' or `##'; the former specifies hex values in the
433 range 0-255 (which are internally multiplied by 257), the latter
434 in the range 0-65535. Examples: `#FFC0CB' (pink), `##ffff0000ffff'
435 (magenta). The default color name value is device-specific
436 (usually black). It is possible that the default color for `\m'
437 and `\M' is not identical.
439 A new scaling indicator `f' has been introduced which multiplies
440 its value by 65536; this makes it convenient to specify color
441 components as fractions in the range 0 to 1 (1f equals 65536u).
445 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
447 Note that `f' is the default scaling indicator for the `defcolor'
448 request, thus the above statement is equivalent to
451 .defcolor darkgreen rgb 0.1 0.5 0.2
457 Set drawing color. The following example shows how to turn the
461 \m[red]these are in red\m[] and these words are in black.
463 The escape `\m[]' returns to the previous color.
465 The drawing color is associated with the current environment
466 (*note Environments::).
468 Note that `\m' doesn't produce an input token in `gtroff'. As a
469 consequence, it can be used in requests like `mc' (which expects a
470 single character as an argument) to change the color on the fly:
479 Set background color for filled objects drawn with the `\D'...''
482 A red ellipse can be created with the following code:
485 \M[red]\h'0.5i'\D'E 2i 1i'\M[]
487 The escape `\M[]' returns to the previous fill color.
489 The fill color is associated with the current environment (*note
492 Note that `\M' doesn't produce an input token in `gtroff'.
495 File: groff, Node: I/O, Next: Postprocessor Access, Prev: Colors, Up: gtroff Reference
500 `gtroff' has several requests for including files:
503 Read in the specified FILE and includes it in place of the `so'
504 request. This is quite useful for large documents, e.g. keeping
505 each chapter in a separate file. *Note gsoelim::, for more
508 Since `gtroff' replaces the `so' request with the contents of
509 `file', it makes a difference whether the data is terminated with
510 a newline or not: Assuming that file `xxx' contains the word `foo'
511 without a final newline, this
518 yields `This is foobar'.
520 - Request: .pso command
521 Read the standard output from the specified COMMAND and includes
522 it in place of the `pso' request.
524 This request causes an error if used in safer mode (which is the
525 default). Use `groff''s or `troff''s `-U' option to activate
528 The comment regarding a final newline for the `so' request is valid
532 Identical to the `so' request except that `gtroff' searches for
533 the specified FILE in the same directories as macro files for the
534 the `-m' command line option. If the file name to be included has
535 the form `NAME.tmac' and it isn't found, `mso' tries to include
536 `tmac.NAME' and vice versa.
540 Transparently output the contents of FILE. Each line is output as
541 if it were preceded by `\!'; however, the lines are not subject to
542 copy mode interpretation. If the file does not end with a newline,
543 then a newline is added (`trf' only). For example, to define a
544 macro `x' containing the contents of file `f', use
551 Both `trf' and `cf', when used in a diversion, embeds an object in
552 the diversion which, when reread, causes the contents of FILE to
553 be transparently copied through to the output. In UNIX `troff',
554 the contents of FILE is immediately copied through to the output
555 regardless of whether there is a current diversion; this behaviour
556 is so anomalous that it must be considered a bug.
558 While `cf' copies the contents of FILE completely unprocessed,
559 `trf' disallows characters such as NUL that are not valid `gtroff'
560 input characters (*note Identifiers::).
562 Both requests cause a line break.
564 - Request: .nx [file]
565 Force `gtroff' to continue processing of the file specified as an
566 argument. If no argument is given, immediately jump to the end of
569 - Request: .rd [prompt [arg1 arg2 ...]]
570 Read from standard input, and include what is read as though it
571 were part of the input file. Text is read until a blank line is
574 If standard input is a TTY input device (keyboard), write PROMPT
575 to standard error, followed by a colon (or send BEL for a beep if
576 no argument is given).
578 Arguments after PROMPT are available for the input. For example,
584 with the input `This is \$2.' prints
590 Using the `nx' and `rd' requests, it is easy to set up form letters.
591 The form letter template is constructed like this, putting the
592 following lines into a file called `repeat.let':
607 When this is run, a file containing the following lines should be
608 redirected in. Note that requests included in this file are executed
609 as though they were part of the form letter. The last block of input
610 is the `ex' request which tells `groff' to stop processing. If this
611 was not there, `groff' would not know when to stop.
615 708 NW 19th Av., #202
629 Pipe the output of `gtroff' to the shell command(s) specified by
630 PIPE. This request must occur before `gtroff' has a chance to
633 `pi' causes an error if used in safer mode (which is the default).
634 Use `groff''s or `troff''s `-U' option to activate unsafe mode.
636 Multiple calls to `pi' are allowed, acting as a chain. For
644 is the same as `.pi foo | bar'.
646 Note that the intermediate output format of `gtroff' is piped to
647 the specified commands. Consequently, calling `groff' without the
648 `-Z' option normally causes a fatal error.
651 - Register: \n[systat]
652 Execute the shell command(s) specified by CMDS. The output is not
653 saved anyplace, so it is up to the user to do so.
655 This request causes an error if used in safer mode (which is the
656 default). Use `groff''s or `troff''s `-U' option to activate
659 For example, the following code fragment introduces the current
660 time into a document:
663 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
664 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
669 Note that this works by having the `perl' script (run by `sy')
670 print out the `nr' requests which set the number registers `H',
671 `M', and `S', and then reads those commands in with the `so'
674 For most practical purposes, the number registers `seconds',
675 `minutes', and `hours' which are initialized at start-up of
676 `gtroff' should be sufficient. Use the `af' request to get a
683 \n[hours]:\n[minutes]:\n[seconds]
685 The `systat' read-write number register contains the return value
686 of the `system()' function executed by the last `sy' request.
688 - Request: .open stream file
689 - Request: .opena stream file
690 Open the specified FILE for writing and associates the specified
693 The `opena' request is like `open', but if the file exists, append
694 to it instead of truncating it.
696 Both `open' and `opena' cause an error if used in safer mode
697 (which is the default). Use `groff''s or `troff''s `-U' option to
698 activate unsafe mode.
700 - Request: .write stream data
701 - Request: .writec stream data
702 Write to the file associated with the specified STREAM. The
703 stream must previously have been the subject of an open request.
704 The remainder of the line is interpreted as the `ds' request reads
705 its second argument: A leading `"' is stripped, and it is read in
708 The `writec' request is like `write', but only `write' appends a
711 - Request: .writem stream xx
712 Write the contents of the macro or string XX to the file
713 associated with the specified STREAM.
715 XX is read in copy mode, i.e., already formatted elements are
716 ignored. Consequently, diversions must be unformatted with the
717 `asciify' request before calling `writem'. Usually, this means a
720 - Request: .close stream
721 Close the specified STREAM; the stream is no longer an acceptable
722 argument to the `write' request.
724 Here a simple macro to write an index entry.
730 . write idx \\n[%] \\$*
741 Interpolate the contents of the specified environment variable ENV
742 (one-character name E, two-character name EV) as returned by the
743 function `getenv'. `\V' is interpreted in copy-in mode.
746 File: groff, Node: Postprocessor Access, Next: Miscellaneous, Prev: I/O, Up: gtroff Reference
751 There are two escapes which give information directly to the
752 postprocessor. This is particularly useful for embedding POSTSCRIPT
753 into the final document.
756 Embeds its argument into the `gtroff' output preceded with `x X'.
758 The escapes `\&', `\)', `\%', and `\:' are ignored within `\X',
759 `\ ' and `\~' are converted to single space characters. All other
760 escapes (except `\\' which produces a backslash) cause an error.
762 If the `use_charnames_in_special' keyword is set in the `DESC'
763 file, special characters no longer cause an error; the name XX is
764 represented as `\(XX)' in the `x X' output command. Additionally,
765 the backslash is represented as `\\'.
767 `use_charnames_in_special' is currently used by `grohtml' only.
772 This is approximately equivalent to `\X'\*[NAME]'' (one-character
773 name N, two-character name NM). However, the contents of the
774 string or macro NAME are not interpreted; also it is permitted for
775 NAME to have been defined as a macro and thus contain newlines (it
776 is not permitted for the argument to `\X' to contain newlines).
777 The inclusion of newlines requires an extension to the UNIX `troff'
778 output format, and confuses drivers that do not know about this
779 extension (*note Device Control Commands::).
781 *Note Output Devices::.
784 File: groff, Node: Miscellaneous, Next: Gtroff Internals, Prev: Postprocessor Access, Up: gtroff Reference
789 This section documents parts of `gtroff' which cannot (yet) be
790 categorized elsewhere in this manual.
792 - Request: .nm [start [inc [space [indent]]]]
793 Print line numbers. START is the line number of the _next_ output
794 line. INC indicates which line numbers are printed. For example,
795 the value 5 means to emit only line numbers which are multiples
796 of 5; this defaults to 1. SPACE is the space to be left between
797 the number and the text; this defaults to one digit space. The
798 fourth argument is the indentation of the line numbers, defaulting
799 to zero. Both SPACE and INDENT are given as multiples of digit
800 spaces; they can be negative also. Without any arguments, line
801 numbers are turned off.
803 `gtroff' reserves three digit spaces for the line number (which is
804 printed right-justified) plus the amount given by INDENT; the
805 output lines are concatenated to the line numbers, separated by
806 SPACE, and _without_ reducing the line length. Depending on the
807 value of the horizontal page offset (as set with the `po'
808 request), line numbers which are longer than the reserved space
809 stick out to the left, or the whole line is moved to the right.
811 Parameters corresponding to missing arguments are not changed; any
812 non-digit argument (to be more precise, any argument starting with
813 a character valid as a delimiter for identifiers) is also treated
816 If line numbering has been disabled with a call to `nm' without an
817 argument, it can be reactivated with `.nm +0', using the
818 previously active line numbering parameters.
820 The parameters of `nm' are associated with the current environment
821 (*note Environments::). The current output line number is
822 available in the number register `ln'.
827 This test shows how line numbering works with groff.
829 This test shows how line numbering works with groff.
833 This test shows how line numbering works with groff.
835 This test shows how line numbering works with groff.
843 1000 test shows how line
844 1001 numbering works with
854 - Request: .nn [skip]
855 Temporarily turn off line numbering. The argument is the number
856 of lines not to be numbered; this defaults to 1.
858 - Request: .mc glyph [dist]
859 Print a "margin character" to the right of the text.(1) (*note
860 Miscellaneous-Footnote-1::) The first argument is the glyph to be
861 printed. The second argument is the distance away from the right
862 margin. If missing, the previously set value is used; default is
863 10pt). For text lines that are too long (that is, longer than the
864 text length plus DIST), the margin character is directly appended
867 With no arguments the margin character is turned off. If this
868 occurs before a break, no margin character is printed.
870 For empty lines and lines produced by the `tl' request no margin
871 character is emitted.
873 The margin character is associated with the current environment
874 (*note Environments::).
876 This is quite useful for indicating text that has changed, and, in
877 fact, there are programs available for doing this (they are called
878 `nrchbar' and `changebar' and can be found in any
879 `comp.sources.unix' archive.
884 This paragraph is highlighted with a margin
887 Note that vertical space isn't marked.
891 But we can fake it with `\&'.
896 This paragraph is highlighted |
897 with a margin character. |
899 Note that vertical space isn't |
902 But we can fake it with `\&'. |
905 - Request: .psbb filename
910 Retrieve the bounding box of the PostScript image found in
911 FILENAME. The file must conform to Adobe's "Document Structuring
912 Conventions" (DSC); the command searches for a `%%BoundingBox'
913 comment and extracts the bounding box values into the number
914 registers `llx', `lly', `urx', and `ury'. If an error occurs (for
915 example, `psbb' cannot find the `%%BoundingBox' comment), it sets
916 the four number registers to zero.
919 File: groff, Node: Miscellaneous-Footnotes, Up: Miscellaneous
921 (1) "Margin character" is a misnomer since it is an output glyph.
924 File: groff, Node: Gtroff Internals, Next: Debugging, Prev: Miscellaneous, Up: gtroff Reference
929 `gtroff' processes input in three steps. One or more input
930 characters are converted to an "input token".(1) (*note Gtroff
931 Internals-Footnote-1::) Then, one or more input tokens are converted
932 to an "output node". Finally, output nodes are converted to the
933 intermediate output language understood by all output devices.
935 Actually, before step one happens, `gtroff' converts certain escape
936 sequences into reserved input characters (not accessible by the user);
937 such reserved characters are used for other internal processing also -
938 this is the very reason why not all characters are valid input. *Note
939 Identifiers::, for more on this topic.
941 For example, the input string `fi\[:u]' is converted into a
942 character token `f', a character token `i', and a special token `:u'
943 (representing u umlaut). Later on, the character tokens `f' and `i'
944 are merged to a single output node representing the ligature glyph `fi'
945 (provided the current font has a glyph for this ligature); the same
946 happens with `:u'. All output glyph nodes are `processed' which means
947 that they are invariably associated with a given font, font size,
948 advance width, etc. During the formatting process, `gtroff' itself
949 adds various nodes to control the data flow.
951 Macros, diversions, and strings collect elements in two chained
952 lists: a list of input tokens which have been passed unprocessed, and a
953 list of output nodes. Consider the following the diversion.
963 It contains these elements.
965 node list token list element number
972 vertical size node -- 7
973 vertical size node -- 8
976 Elements 1, 7, and 8 are inserted by `gtroff'; the latter two (which
977 are always present) specify the vertical extent of the last line,
978 possibly modified by `\x'. The `br' request finishes the current
979 partial line, inserting a newline input token which is subsequently
980 converted to a space when the diversion is reread. Note that the word
981 space node has a fixed width which isn't stretchable anymore. To
982 convert horizontal space nodes back to input tokens, use the `unformat'
985 Macros only contain elements in the token list (and the node list is
986 empty); diversions and strings can contain elements in both lists.
988 Note that the `chop' request simply reduces the number of elements
989 in a macro, string, or diversion by one. Exceptions are "compatibility
990 save" and "compatibility ignore" input tokens which are ignored. The
991 `substring' request also ignores those input tokens.
993 Some requests like `tr' or `cflags' work on glyph identifiers only;
994 this means that the associated glyph can be changed without destroying
995 this association. This can be very helpful for substituting glyphs.
996 In the following example, we assume that glyph `foo' isn't available by
997 default, so we provide a substitution using the `fchar' request and map
998 it to input character `x'.
1004 Now let us assume that we install an additional special font `bar'
1005 which has glyph `foo'.
1011 Since glyphs defined with `fchar' are searched before glyphs in special
1012 fonts, we must call `rchar' to remove the definition of the fallback
1013 glyph. Anyway, the translation is still active; `x' now maps to the
1017 File: groff, Node: Gtroff Internals-Footnotes, Up: Gtroff Internals
1019 (1) Except the escapes `\f', `\F', `\H', `\m', `\M', `\R', `\s', and
1020 `\S' which are processed immediately if not in copy-in mode.
1023 File: groff, Node: Debugging, Next: Implementation Differences, Prev: Gtroff Internals, Up: gtroff Reference
1028 `gtroff' is not easy to debug, but there are some useful features
1029 and strategies for debugging.
1031 - Request: .lf line filename
1032 Change the line number and the file name `gtroff' shall use for
1033 error and warning messages. LINE is the input line number of the
1036 Without argument, the request is ignored.
1038 This is a debugging aid for documents which are split into many
1039 files, then put together with `soelim' and other preprocessors.
1040 Usually, it isn't invoked manually.
1042 - Request: .tm string
1043 - Request: .tm1 string
1044 - Request: .tmc string
1045 Send STRING to the standard error output; this is very useful for
1046 printing debugging messages among other things.
1048 STRING is read in copy mode.
1050 The `tm' request ignores leading spaces of STRING; `tm1' handles
1051 its argument similar to the `ds' request: a leading double quote
1052 in STRING is stripped to allow initial blanks.
1054 The `tmc' request is similar to `tm1' but does not append a
1055 newline (as is done in `tm' and `tm1').
1057 - Request: .ab [string]
1058 Similar to the `tm' request, except that it causes `gtroff' to
1059 stop processing. With no argument it prints `User Abort.' to
1063 The `ex' request also causes `gtroff' to stop processing; see also
1066 When doing something involved it is useful to leave the debugging
1067 statements in the code and have them turned on by a command line flag.
1070 .if \n(DB .tm debugging output
1072 To activate these statements say
1077 If it is known in advance that there will be many errors and no
1078 useful output, `gtroff' can be forced to suppress formatted output with
1082 Print the entire symbol table on `stderr'. Names of all defined
1083 macros, strings, and diversions are print together with their size
1084 in bytes. Since `gtroff' sometimes adds nodes by itself, the
1085 returned size can be larger than expected.
1087 This request differs from UNIX `troff': `gtroff' reports the sizes
1088 of diversions, ignores an additional argument to print only the
1089 total of the sizes, and the size isn't returned in blocks of 128
1093 Print the names and contents of all currently defined number
1094 registers on `stderr'.
1097 Print the names and positions of all traps (not including input
1098 line traps and diversion traps) on `stderr'. Empty slots in the
1099 page trap list are printed as well, because they can affect the
1100 priority of subsequently planted traps.
1103 Instruct `gtroff' to flush its output immediately. The intent is
1104 for interactive use, but this behaviour is currently not
1105 implemented in `gtroff'. Contrary to UNIX `troff', TTY output is
1106 sent to a device driver also (`grotty'), making it non-trivial to
1107 communicate interactively.
1109 This request causes a line break.
1111 - Request: .backtrace
1112 Print a backtrace of the input stack to the standard error stream.
1114 Consider the following in file `test':
1126 On execution, `gtroff' prints the following:
1129 test:2: backtrace: macro `xxx'
1130 test:5: backtrace: macro `yyy'
1131 test:8: backtrace: file `test'
1133 The option `-b' of `gtroff' internally calls a variant of this
1134 request on each error and warning.
1136 - Register: \n[slimit]
1137 Use the `slimit' number register to set the maximum number of
1138 objects on the input stack. If `slimit' is less than or equal
1139 to 0, there is no limit set. With no limit, a buggy recursive
1140 macro can exhaust virtual memory.
1142 The default value is 1000; this is a compile-time constant.
1144 - Request: .warnscale si
1145 Set the scaling indicator used in warnings to SI. Valid values for
1146 SI are `u', `i', `c', `p', and `P'. At startup, it is set to `i'.
1148 - Request: .spreadwarn [limit]
1149 Make `gtroff' emit a warning if the additional space inserted for
1150 each space between words in an output line is larger or equal to
1151 LIMIT. A negative value is changed to zero; no argument toggles
1152 the warning on and off without changing LIMIT. The default scaling
1153 indicator is `m'. At startup, `spreadwarn' is deactivated, and
1161 will cause a warning if `gtroff' must add 0.2m or more for each
1162 interword space in a line.
1164 This request is active only if text is justified to both margins
1167 `gtroff' has command line options for printing out more warnings
1168 (`-w') and for printing backtraces (`-b') when a warning or an error
1169 occurs. The most verbose level of warnings is `-ww'.
1171 - Request: .warn [flags]
1172 - Register: \n[.warn]
1173 Control the level of warnings checked for. The FLAGS are the sum
1174 of the numbers associated with each warning that is to be enabled;
1175 all other warnings are disabled. The number associated with each
1176 warning is listed below. For example, `.warn 0' disables all
1177 warnings, and `.warn 1' disables all warnings except that about
1178 missing glyphs. If no argument is given, all warnings are enabled.
1180 The read-only number register `.warn' contains the current warning
1188 File: groff, Node: Warnings, Prev: Debugging, Up: Debugging
1193 The warnings that can be given to `gtroff' are divided into the
1194 following categories. The name associated with each warning is used by
1195 the `-w' and `-W' options; the number is used by the `warn' request and
1196 by the `.warn' register.
1200 Non-existent glyphs.(1) (*note Warnings-Footnote-1::) This is
1205 Invalid numeric expressions. This is enabled by default. *Note
1210 In fill mode, lines which could not be broken so that their length
1211 was less than the line length. This is enabled by default.
1215 Missing or mismatched closing delimiters.
1219 Use of the `el' request with no matching `ie' request. *Note
1224 Meaningless scaling indicators.
1228 Out of range arguments.
1232 Dubious syntax in numeric expressions.
1236 Use of `di' or `da' without an argument when there is no current
1241 Use of undefined strings, macros and diversions. When an undefined
1242 string, macro, or diversion is used, that string is automatically
1243 defined as empty. So, in most cases, at most one warning is given
1248 Use of undefined number registers. When an undefined number
1249 register is used, that register is automatically defined to have a
1250 value of 0. So, in most cases, at most one warning is given for
1251 use of a particular name.
1255 Use of a tab character where a number was expected.
1259 Use of `\}' where a number was expected.
1263 Requests that are missing non-optional arguments.
1267 Invalid input characters.
1271 Unrecognized escape sequences. When an unrecognized escape
1272 sequence `\X' is encountered, the escape character is ignored, and
1277 Missing space between a request or macro and its argument. This
1278 warning is given when an undefined name longer than two characters
1279 is encountered, and the first two characters of the name make a
1280 defined name. The request or macro is not invoked. When this
1281 warning is given, no macro is automatically defined. This is
1282 enabled by default. This warning never occurs in compatibility
1287 Non-existent fonts. This is enabled by default.
1291 Invalid escapes in text ignored with the `ig' request. These are
1292 conditions that are errors when they do not occur in ignored text.
1296 Color related warnings.
1299 All warnings except `di', `mac' and `reg'. It is intended that
1300 this covers all warnings that are useful with traditional macro
1307 File: groff, Node: Warnings-Footnotes, Up: Warnings
1309 (1) `char' is a misnomer since it reports missing glyphs - there
1310 aren't missing input characters, only invalid ones.
1313 File: groff, Node: Implementation Differences, Prev: Debugging, Up: gtroff Reference
1315 Implementation Differences
1316 ==========================
1318 GNU `troff' has a number of features which cause incompatibilities
1319 with documents written with old versions of `troff'.
1321 Long names cause some incompatibilities. UNIX `troff' interprets
1326 as defining a string `ab' with contents `cd'. Normally, GNU `troff'
1327 interprets this as a call of a macro named `dsabcd'. Also UNIX `troff'
1328 interprets `\*[' or `\n[' as references to a string or number register
1329 called `['. In GNU `troff', however, this is normally interpreted as
1330 the start of a long name. In compatibility mode GNU `troff' interprets
1331 long names in the traditional way (which means that they are not
1332 recognized as names).
1337 If N is missing or non-zero, turn on compatibility mode;
1338 otherwise, turn it off.
1340 The read-only number register `.C' is 1 if compatibility mode is
1343 Compatibility mode can be also turned on with the `-C' command line
1346 The `do' request turns off compatibility mode while executing its
1347 arguments as a `gtroff' command.
1352 executes the `fam' request when compatibility mode is enabled.
1354 `gtroff' restores the previous compatibility setting before
1355 interpreting any files sourced by the CMD.
1357 Two other features are controlled by `-C'. If not in compatibility
1358 mode, GNU `troff' preserves the input level in delimited arguments:
1364 In compatibility mode, the string `72def'' is returned; without `-C'
1365 the resulting string is `168' (assuming a TTY output device).
1367 Finally, the escapes `\f', `\H', `\m', `\M', `\R', `\s', and `\S'
1368 are transparent for recognizing the beginning of a line only in
1369 compatibility mode (this is a rather obscure feature). For example,
1378 prints `Hallo!' in bold face if in compatibility mode, and `.xx' in
1379 bold face otherwise.
1381 GNU `troff' does not allow the use of the escape sequences `\|',
1382 `\^', `\&', `\{', `\}', `\<SP>', `\'', `\`', `\-', `\_', `\!', `\%',
1383 and `\c' in names of strings, macros, diversions, number registers,
1384 fonts or environments; UNIX `troff' does. The `\A' escape sequence
1385 (*note Identifiers::) may be helpful in avoiding use of these escape
1388 Fractional point sizes cause one noteworthy incompatibility. In
1389 UNIX `troff' the `ps' request ignores scale indicators and thus
1394 sets the point size to 10 points, whereas in GNU `troff' it sets the
1395 point size to 10 scaled points. *Note Fractional Type Sizes::, for
1398 In GNU `troff' there is a fundamental difference between
1399 (unformatted) input characters and (formatted) output glyphs.
1400 Everything that affects how a glyph is output is stored with the glyph
1401 node; once a glyph node has been constructed it is unaffected by any
1402 subsequent requests that are executed, including `bd', `cs', `tkf',
1403 `tr', or `fp' requests. Normally glyphs are constructed from input
1404 characters at the moment immediately before the glyph is added to the
1405 current output line. Macros, diversions and strings are all, in fact,
1406 the same type of object; they contain lists of input characters and
1407 glyph nodes in any combination. A glyph node does not behave like an
1408 input character for the purposes of macro processing; it does not
1409 inherit any of the special properties that the input character from
1410 which it was constructed might have had. For example,
1419 prints `\\' in GNU `troff'; each pair of input backslashes is turned
1420 into one output backslash and the resulting output backslashes are not
1421 interpreted as escape characters when they are reread. UNIX `troff'
1422 would interpret them as escape characters when they were reread and
1423 would end up printing one `\'. The correct way to obtain a printable
1424 backslash is to use the `\e' escape sequence: This always prints a
1425 single instance of the current escape character, regardless of whether
1426 or not it is used in a diversion; it also works in both GNU `troff' and
1427 UNIX `troff'.(1) (*note Implementation Differences-Footnote-1::) To
1428 store, for some reason, an escape sequence in a diversion that will be
1429 interpreted when the diversion is reread, either use the traditional
1430 `\!' transparent output facility, or, if this is unsuitable, the new
1431 `\?' escape sequence.
1433 *Note Diversions::, and *Note Gtroff Internals::, for more
1437 File: groff, Node: Implementation Differences-Footnotes, Up: Implementation Differences
1439 (1) To be completely independent of the current escape character,
1440 use `\(rs' which represents a reverse solidus (backslash) glyph.
1443 File: groff, Node: Preprocessors, Next: Output Devices, Prev: gtroff Reference, Up: Top
1448 This chapter describes all preprocessors that come with `groff' or
1449 which are freely available.
1462 File: groff, Node: geqn, Next: gtbl, Prev: Preprocessors, Up: Preprocessors
1472 File: groff, Node: Invoking geqn, Prev: geqn, Up: geqn
1478 File: groff, Node: gtbl, Next: gpic, Prev: geqn, Up: Preprocessors
1488 File: groff, Node: Invoking gtbl, Prev: gtbl, Up: gtbl
1494 File: groff, Node: gpic, Next: ggrn, Prev: gtbl, Up: Preprocessors
1504 File: groff, Node: Invoking gpic, Prev: gpic, Up: gpic
1510 File: groff, Node: ggrn, Next: grap, Prev: gpic, Up: Preprocessors
1520 File: groff, Node: Invoking ggrn, Prev: ggrn, Up: ggrn
1526 File: groff, Node: grap, Next: grefer, Prev: ggrn, Up: Preprocessors
1531 A free implementation of `grap', written by Ted Faber, is available
1532 as an extra package from the following address:
1534 <http://www.lunabase.org/~faber/Vault/software/grap/>
1537 File: groff, Node: grefer, Next: gsoelim, Prev: grap, Up: Preprocessors
1547 File: groff, Node: Invoking grefer, Prev: grefer, Up: grefer
1553 File: groff, Node: gsoelim, Prev: grefer, Up: Preprocessors
1560 * Invoking gsoelim::
1563 File: groff, Node: Invoking gsoelim, Prev: gsoelim, Up: gsoelim
1569 File: groff, Node: Output Devices, Next: File formats, Prev: Preprocessors, Up: Top
1576 * Special Characters::
1586 File: groff, Node: Special Characters, Next: grotty, Prev: Output Devices, Up: Output Devices
1594 File: groff, Node: grotty, Next: grops, Prev: Special Characters, Up: Output Devices
1604 File: groff, Node: Invoking grotty, Prev: grotty, Up: grotty