diff options
Diffstat (limited to 'contrib/groff/doc/groff-7')
| -rw-r--r-- | contrib/groff/doc/groff-7 | 1608 |
1 files changed, 1608 insertions, 0 deletions
diff --git a/contrib/groff/doc/groff-7 b/contrib/groff/doc/groff-7 new file mode 100644 index 0000000..382e218 --- /dev/null +++ b/contrib/groff/doc/groff-7 @@ -0,0 +1,1608 @@ +This is groff, produced by makeinfo version 4.2 from ./groff.texinfo. + +This manual documents GNU `troff' version 1.18. + + Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover texts + being `A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + `GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: `You have freedom to copy and + modify this GNU Manual, like GNU software. Copies published by + the Free Software Foundation raise funds for GNU development." + +INFO-DIR-SECTION Miscellaneous +START-INFO-DIR-ENTRY +* Groff: (groff). The GNU troff document formatting system. +END-INFO-DIR-ENTRY + + +File: groff, Node: Diversions, Next: Environments, Prev: Traps, Up: gtroff Reference + +Diversions +========== + + In `gtroff' it is possible to "divert" text into a named storage +area. Due to the similarity to defining macros it is sometimes said to +be stored in a macro. This is used for saving text for output at a +later time, which is useful for keeping blocks of text on the same +page, footnotes, tables of contents, and indices. + + For orthogonality it is said that `gtroff' is in the "top-level +diversion" if no diversion is active (i.e., the data is diverted to the +output device). + + - Request: .di macro + - Request: .da macro + Begin a diversion. Like the `de' request, it takes an argument of + a macro name to divert subsequent text into. The `da' macro + appends to an existing diversion. + + `di' or `da' without an argument ends the diversion. + + - Request: .box macro + - Request: .boxa macro + Begin (or appends to) a diversion like the `di' and `da' requests. + The difference is that `box' and `boxa' do not include a + partially-filled line in the diversion. + + Compare this: + + + Before the box. + .box xxx + In the box. + .br + .box + After the box. + .br + => Before the box. After the box. + .xxx + => In the box. + + with this: + + + Before the diversion. + .di yyy + In the diversion. + .br + .di + After the diversion. + .br + => After the diversion. + .yyy + => Before the diversion. In the diversion. + + `box' or `boxa' without an argument ends the diversion. + + - Register: \n[.z] + - Register: \n[.d] + Diversions may be nested. The read-only number register `.z' + contains the name of the current diversion (this is a string-valued + register). The read-only number register `.d' contains the current + vertical place in the diversion. If not in a diversion it is the + same as the register `nl'. + + - Register: \n[.h] + The "high-water mark" on the current page. It corresponds to the + text baseline of the lowest line on the page. This is a read-only + register. + + + .tm .h==\n[.h], nl==\n[nl] + => .h==0, nl==-1 + This is a test. + .br + .sp 2 + .tm .h==\n[.h], nl==\n[nl] + => .h==40, nl==120 + + As can be seen in the previous example, empty lines are not + considered in the return value of the `.h' register. + + - Register: \n[dn] + - Register: \n[dl] + After completing a diversion, the read-write number registers `dn' + and `dl' contain the vertical and horizontal size of the diversion. + + + .\" Center text both horizontally & vertically + . + .\" Enclose macro definitions in .eo and .ec + .\" to avoid the doubling of the backslash + .eo + .\" macro .(c starts centering mode + .de (c + . br + . ev (c + . evc 0 + . in 0 + . nf + . di @c + .. + + + .\" macro .)c terminates centering mode + .de )c + . br + . ev + . di + . nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v) + . sp \n[@s]u + . ce 1000 + . @c + . ce 0 + . sp \n[@s]u + . br + . fi + . rr @s + . rm @s + . rm @c + .. + .\" End of macro definitions, restore escape mechanism + .ec + + + - Escape: \! + - Escape: \?ANYTHING\? + Prevent requests, macros, and escapes from being interpreted when + read into a diversion. This takes the given text and + "transparently" embeds it into the diversion. This is useful for + macros which shouldn't be invoked until the diverted text is + actually output. + + The `\!' escape transparently embeds text up to and including the + end of the line. The `\?' escape transparently embeds text until + the next occurrence of the `\?' escape. For example: + + + \?ANYTHING\? + + ANYTHING may not contain newlines; use `\!' to embed newlines in + a diversion. The escape sequence `\?' is also recognized in copy + mode and turned into a single internal code; it is this code that + terminates ANYTHING. Thus the following example prints 4. + + + .nr x 1 + .nf + .di d + \?\\?\\\\?\\\\\\\\nx\\\\?\\?\? + .di + .nr x 2 + .di e + .d + .di + .nr x 3 + .di f + .e + .di + .nr x 4 + .f + + Both escapes read the data in copy mode. + + If `\!' is used in the top-level diversion, its argument is + directly embedded into the `gtroff' intermediate output. This can + be used for example to control a postprocessor which processes the + data before it is sent to the device driver. + + The `\?' escape used in the top-level diversion produces no output + at all; its argument is simply ignored. + + - Request: .output string + Emit STRING directly to the `gtroff' intermediate output (subject + to copy-mode interpretation); this is similar to `\!' used at the + top level. An initial double quote in STRING is stripped off to + allow initial blanks. + + This request can't be used before the first page has started - if + you get an error, simply insert `.br' before the `output' request. + + Without argument, `output' is ignored. + + Use with caution! It is normally only needed for mark-up used by a + postprocessor which does something with the output before sending + it to the output device, filtering out `string' again. + + - Request: .asciify div + "Unformat" the diversion specified by DIV in such a way that ASCII + characters, characters translated with the `trin' request, space + characters, and some escape sequences that were formatted and + diverted are treated like ordinary input characters when the + diversion is reread. It can be also used for gross hacks; for + example, the following sets register `n' to 1. + + + .tr @. + .di x + @nr n 1 + .br + .di + .tr @@ + .asciify x + .x + + *Note Copy-in Mode::. + + - Request: .unformat div + Like `asciify', unformat the specified diversion. However, + `unformat' only unformats spaces and tabs between words. + Unformatted tabs are treated as input tokens, and spaces are + stretchable again. + + The vertical size of lines is not preserved; glyph information + (font, font size, space width, etc.) is retained. + + +File: groff, Node: Environments, Next: Suppressing output, Prev: Diversions, Up: gtroff Reference + +Environments +============ + + It happens frequently that some text should be printed in a certain +format regardless of what may be in effect at the time, for example, in +a trap invoked macro to print headers and footers. To solve this +`gtroff' processes text in "environments". An environment contains +most of the parameters that control text processing. It is possible to +switch amongst these environments; by default `gtroff' processes text +in environment 0. The following is the information kept in an +environment. + + * font parameters (size, family, style, glyph height and slant, space + and sentence space size) + + * page parameters (line length, title length, vertical spacing, line + spacing, indentation, line numbering, centering, right-justifying, + underlining, hyphenation data) + + * fill and adjust mode + + * tab stops, tab and leader characters, escape character, no-break + and hyphen indicators, margin character data + + * partially collected lines + + * input traps + + * drawing and fill colours + + These environments may be given arbitrary names (see *Note +Identifiers::, for more info). Old versions of `troff' only had +environments named `0', `1', and `2'. + + - Request: .ev [env] + - Register: \n[.ev] + Switch to another environment. The argument ENV is the name of + the environment to switch to. With no argument, `gtroff' switches + back to the previous environment. There is no limit on the number + of named environments; they are created the first time that they + are referenced. The `.ev' read-only register contains the name or + number of the current environment. This is a string-valued + register. + + Note that a call to `ev' (with argument) pushes the previously + active environment onto a stack. If, say, environments `foo', + `bar', and `zap' are called (in that order), the first `ev' + request without parameter switches back to environment `bar' + (which is popped off the stack), and a second call switches back + to environment `foo'. + + Here is an example: + + + .ev footnote-env + .fam N + .ps 6 + .vs 8 + .ll -.5i + .ev + + ... + + .ev footnote-env + \(dg Note the large, friendly letters. + .ev + + + - Request: .evc env + Copy the environment ENV into the current environment. + + The following environment data is not copied: + + * Partially filled lines. + + * The status whether the previous line was interrupted. + + * The number of lines still to center, or to right-justify, or + to underline (with or without underlined spaces); they are + set to zero. + + * The status whether a temporary indent is active. + + * Input traps and its associated data. + + * Line numbering mode is disabled; it can be reactivated with + `.nm +0'. + + * The number of consecutive hyphenated lines (set to zero). + + - Register: \n[.cht] + - Register: \n[.cdp] + - Register: \n[.csk] + The `\n[.cht]' register contains the maximum extent (above the + baseline) of the last glyph added to the current environment. + + The `\n[.cdp]' register contains the maximum extent (below the + baseline) of the last glyph added to the current environment. + + The `\n[.csk]' register contains the "skew" (how far to the right + of the glyph's center that `gtroff' shold place an accent) of the + last glyph added to the current environment. + + +File: groff, Node: Suppressing output, Next: Colors, Prev: Environments, Up: gtroff Reference + +Suppressing output +================== + + - Escape: \ONUM + Disable or enable output depending on the value of NUM: + + `\O0' + Disable any glyphs from being emitted to the device driver, + provided that the escape occurs at the outer level (see + `\O[3]' and `\O[4]'). Motion is not suppressed so + effectively `\O[0]' means _pen up_. + + `\O1' + Enable output of glyphs, provided that the escape occurs at + the outer level. + + `\O0' and `\O1' also reset the four registers `opminx', `opminy', + `opmaxx', and `opmaxy' to -1. *Note Register Index::. These four + registers mark the top left and bottom right hand corners of a box + which encompasses all written glyphs. + + For example the input text: + + + Hello \O[0]world \O[1]this is a test. + + produces the following output: + + + Hello this is a test. + + `\O2' + Provided that the escape occurs at the outer level, enable + output of glyphs and also write out to `stderr' the page + number and four registers encompassing the glyphs previously + written since the last call to `\O'. + + `\O3' + Begin a nesting level. At start-up, `gtroff' is at outer + level. + + `\O4' + End a nesting level. + + `\O[5PFILENAME]' + This escape is `grohtml' specific. Provided that this escape + occurs at the outer nesting level write the `filename' to + `stderr'. The position of the image, P, must be specified + and must be one of `l', `r', `c', or `i' (left, right, + centered, inline). FILENAME will be associated with the + production of the next inline image. + + +File: groff, Node: Colors, Next: I/O, Prev: Suppressing output, Up: gtroff Reference + +Colors +====== + + - Request: .color [n] + - Register: \n[.color] + If N is missing or non-zero, activate colors (this is the default); + otherwise, turn it off. + + The read-only number register `.color' is 1 if colors are active, + 0 otherwise. + + Internally, `color' sets a global flag; it does not produce a + token. Similar to the `cp' request, you should use it at the + beginning of your document to control color output. + + Colors can be also turned off with the `-c' command line option. + + - Request: .defcolor ident scheme color_components + Define color with name IDENT. SCHEME can be one of the following + values: `rgb' (three components), `cym' (three components), `cmyk' + (four components), and `gray' or `grey' (one component). + + Color components can be given either as a hexadecimal string or as + positive decimal integers in the range 0-65535. A hexadecimal + string contains all color components concatenated. It must start + with either `#' or `##'; the former specifies hex values in the + range 0-255 (which are internally multiplied by 257), the latter + in the range 0-65535. Examples: `#FFC0CB' (pink), `##ffff0000ffff' + (magenta). The default color name value is device-specific + (usually black). It is possible that the default color for `\m' + and `\M' is not identical. + + A new scaling indicator `f' has been introduced which multiplies + its value by 65536; this makes it convenient to specify color + components as fractions in the range 0 to 1 (1f equals 65536u). + Example: + + + .defcolor darkgreen rgb 0.1f 0.5f 0.2f + + Note that `f' is the default scaling indicator for the `defcolor' + request, thus the above statement is equivalent to + + + .defcolor darkgreen rgb 0.1 0.5 0.2 + + + - Escape: \mC + - Escape: \m(CO + - Escape: \m[COLOR] + Set drawing color. The following example shows how to turn the + next four words red. + + + \m[red]these are in red\m[] and these words are in black. + + The escape `\m[]' returns to the previous color. + + The drawing color is associated with the current environment + (*note Environments::). + + Note that `\m' doesn't produce an input token in `gtroff'. As a + consequence, it can be used in requests like `mc' (which expects a + single character as an argument) to change the color on the fly: + + + .mc \m[red]x\m[] + + + - Escape: \MC + - Escape: \M(CO + - Escape: \M[COLOR] + Set background color for filled objects drawn with the `\D'...'' + commands. + + A red ellipse can be created with the following code: + + + \M[red]\h'0.5i'\D'E 2i 1i'\M[] + + The escape `\M[]' returns to the previous fill color. + + The fill color is associated with the current environment (*note + Environments::). + + Note that `\M' doesn't produce an input token in `gtroff'. + + +File: groff, Node: I/O, Next: Postprocessor Access, Prev: Colors, Up: gtroff Reference + +I/O +=== + + `gtroff' has several requests for including files: + + - Request: .so file + Read in the specified FILE and includes it in place of the `so' + request. This is quite useful for large documents, e.g. keeping + each chapter in a separate file. *Note gsoelim::, for more + information. + + Since `gtroff' replaces the `so' request with the contents of + `file', it makes a difference whether the data is terminated with + a newline or not: Assuming that file `xxx' contains the word `foo' + without a final newline, this + + + This is + .so xxx + bar + + yields `This is foobar'. + + - Request: .pso command + Read the standard output from the specified COMMAND and includes + it in place of the `pso' request. + + This request causes an error if used in safer mode (which is the + default). Use `groff''s or `troff''s `-U' option to activate + unsafe mode. + + The comment regarding a final newline for the `so' request is valid + for `pso' also. + + - Request: .mso file + Identical to the `so' request except that `gtroff' searches for + the specified FILE in the same directories as macro files for the + the `-m' command line option. If the file name to be included has + the form `NAME.tmac' and it isn't found, `mso' tries to include + `tmac.NAME' and vice versa. + + - Request: .trf file + - Request: .cf file + Transparently output the contents of FILE. Each line is output as + if it were preceded by `\!'; however, the lines are not subject to + copy mode interpretation. If the file does not end with a newline, + then a newline is added (`trf' only). For example, to define a + macro `x' containing the contents of file `f', use + + + .di x + .trf f + .di + + Both `trf' and `cf', when used in a diversion, embeds an object in + the diversion which, when reread, causes the contents of FILE to + be transparently copied through to the output. In UNIX `troff', + the contents of FILE is immediately copied through to the output + regardless of whether there is a current diversion; this behaviour + is so anomalous that it must be considered a bug. + + While `cf' copies the contents of FILE completely unprocessed, + `trf' disallows characters such as NUL that are not valid `gtroff' + input characters (*note Identifiers::). + + Both requests cause a line break. + + - Request: .nx [file] + Force `gtroff' to continue processing of the file specified as an + argument. If no argument is given, immediately jump to the end of + file. + + - Request: .rd [prompt [arg1 arg2 ...]] + Read from standard input, and include what is read as though it + were part of the input file. Text is read until a blank line is + encountered. + + If standard input is a TTY input device (keyboard), write PROMPT + to standard error, followed by a colon (or send BEL for a beep if + no argument is given). + + Arguments after PROMPT are available for the input. For example, + the line + + + .rd data foo bar + + with the input `This is \$2.' prints + + + This is bar. + + + Using the `nx' and `rd' requests, it is easy to set up form letters. +The form letter template is constructed like this, putting the +following lines into a file called `repeat.let': + + + .ce + \*(td + .sp 2 + .nf + .rd + .sp + .rd + .fi + Body of letter. + .bp + .nx repeat.let + +When this is run, a file containing the following lines should be +redirected in. Note that requests included in this file are executed +as though they were part of the form letter. The last block of input +is the `ex' request which tells `groff' to stop processing. If this +was not there, `groff' would not know when to stop. + + + Trent A. Fisher + 708 NW 19th Av., #202 + Portland, OR 97209 + + Dear Trent, + + Len Adollar + 4315 Sierra Vista + San Diego, CA 92103 + + Dear Mr. Adollar, + + .ex + + - Request: .pi pipe + Pipe the output of `gtroff' to the shell command(s) specified by + PIPE. This request must occur before `gtroff' has a chance to + print anything. + + `pi' causes an error if used in safer mode (which is the default). + Use `groff''s or `troff''s `-U' option to activate unsafe mode. + + Multiple calls to `pi' are allowed, acting as a chain. For + example, + + + .pi foo + .pi bar + ... + + is the same as `.pi foo | bar'. + + Note that the intermediate output format of `gtroff' is piped to + the specified commands. Consequently, calling `groff' without the + `-Z' option normally causes a fatal error. + + - Request: .sy cmds + - Register: \n[systat] + Execute the shell command(s) specified by CMDS. The output is not + saved anyplace, so it is up to the user to do so. + + This request causes an error if used in safer mode (which is the + default). Use `groff''s or `troff''s `-U' option to activate + unsafe mode. + + For example, the following code fragment introduces the current + time into a document: + + + .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ + (localtime(time))[2,1,0]' > /tmp/x\n[$$] + .so /tmp/x\n[$$] + .sy rm /tmp/x\n[$$] + \nH:\nM:\nS + + Note that this works by having the `perl' script (run by `sy') + print out the `nr' requests which set the number registers `H', + `M', and `S', and then reads those commands in with the `so' + request. + + For most practical purposes, the number registers `seconds', + `minutes', and `hours' which are initialized at start-up of + `gtroff' should be sufficient. Use the `af' request to get a + formatted output: + + + .af hours 00 + .af minutes 00 + .af seconds 00 + \n[hours]:\n[minutes]:\n[seconds] + + The `systat' read-write number register contains the return value + of the `system()' function executed by the last `sy' request. + + - Request: .open stream file + - Request: .opena stream file + Open the specified FILE for writing and associates the specified + STREAM with it. + + The `opena' request is like `open', but if the file exists, append + to it instead of truncating it. + + Both `open' and `opena' cause an error if used in safer mode + (which is the default). Use `groff''s or `troff''s `-U' option to + activate unsafe mode. + + - Request: .write stream data + - Request: .writec stream data + Write to the file associated with the specified STREAM. The + stream must previously have been the subject of an open request. + The remainder of the line is interpreted as the `ds' request reads + its second argument: A leading `"' is stripped, and it is read in + copy-in mode. + + The `writec' request is like `write', but only `write' appends a + newline to the data. + + - Request: .writem stream xx + Write the contents of the macro or string XX to the file + associated with the specified STREAM. + + XX is read in copy mode, i.e., already formatted elements are + ignored. Consequently, diversions must be unformatted with the + `asciify' request before calling `writem'. Usually, this means a + loss of information. + + - Request: .close stream + Close the specified STREAM; the stream is no longer an acceptable + argument to the `write' request. + + Here a simple macro to write an index entry. + + + .open idx test.idx + . + .de IX + . write idx \\n[%] \\$* + .. + . + .IX test entry + . + .close idx + + + - Escape: \VE + - Escape: \V(EV + - Escape: \V[ENV] + Interpolate the contents of the specified environment variable ENV + (one-character name E, two-character name EV) as returned by the + function `getenv'. `\V' is interpreted in copy-in mode. + + +File: groff, Node: Postprocessor Access, Next: Miscellaneous, Prev: I/O, Up: gtroff Reference + +Postprocessor Access +==================== + + There are two escapes which give information directly to the +postprocessor. This is particularly useful for embedding POSTSCRIPT +into the final document. + + - Escape: \X'XXX' + Embeds its argument into the `gtroff' output preceded with `x X'. + + The escapes `\&', `\)', `\%', and `\:' are ignored within `\X', + `\ ' and `\~' are converted to single space characters. All other + escapes (except `\\' which produces a backslash) cause an error. + + If the `use_charnames_in_special' keyword is set in the `DESC' + file, special characters no longer cause an error; the name XX is + represented as `\(XX)' in the `x X' output command. Additionally, + the backslash is represented as `\\'. + + `use_charnames_in_special' is currently used by `grohtml' only. + + - Escape: \YN + - Escape: \Y(NM + - Escape: \Y[NAME] + This is approximately equivalent to `\X'\*[NAME]'' (one-character + name N, two-character name NM). However, the contents of the + string or macro NAME are not interpreted; also it is permitted for + NAME to have been defined as a macro and thus contain newlines (it + is not permitted for the argument to `\X' to contain newlines). + The inclusion of newlines requires an extension to the UNIX `troff' + output format, and confuses drivers that do not know about this + extension (*note Device Control Commands::). + + *Note Output Devices::. + + +File: groff, Node: Miscellaneous, Next: Gtroff Internals, Prev: Postprocessor Access, Up: gtroff Reference + +Miscellaneous +============= + + This section documents parts of `gtroff' which cannot (yet) be +categorized elsewhere in this manual. + + - Request: .nm [start [inc [space [indent]]]] + Print line numbers. START is the line number of the _next_ output + line. INC indicates which line numbers are printed. For example, + the value 5 means to emit only line numbers which are multiples + of 5; this defaults to 1. SPACE is the space to be left between + the number and the text; this defaults to one digit space. The + fourth argument is the indentation of the line numbers, defaulting + to zero. Both SPACE and INDENT are given as multiples of digit + spaces; they can be negative also. Without any arguments, line + numbers are turned off. + + `gtroff' reserves three digit spaces for the line number (which is + printed right-justified) plus the amount given by INDENT; the + output lines are concatenated to the line numbers, separated by + SPACE, and _without_ reducing the line length. Depending on the + value of the horizontal page offset (as set with the `po' + request), line numbers which are longer than the reserved space + stick out to the left, or the whole line is moved to the right. + + Parameters corresponding to missing arguments are not changed; any + non-digit argument (to be more precise, any argument starting with + a character valid as a delimiter for identifiers) is also treated + as missing. + + If line numbering has been disabled with a call to `nm' without an + argument, it can be reactivated with `.nm +0', using the + previously active line numbering parameters. + + The parameters of `nm' are associated with the current environment + (*note Environments::). The current output line number is + available in the number register `ln'. + + + .po 1m + .ll 2i + This test shows how line numbering works with groff. + .nm 999 + This test shows how line numbering works with groff. + .br + .nm xxx 3 2 + .ll -\w'0'u + This test shows how line numbering works with groff. + .nn 2 + This test shows how line numbering works with groff. + + And here the result: + + + This test shows how + line numbering works + 999 with groff. This + 1000 test shows how line + 1001 numbering works with + 1002 groff. + This test shows how + line numbering + works with groff. + This test shows how + 1005 line numbering + works with groff. + + + - Request: .nn [skip] + Temporarily turn off line numbering. The argument is the number + of lines not to be numbered; this defaults to 1. + + - Request: .mc glyph [dist] + Print a "margin character" to the right of the text.(1) (*note + Miscellaneous-Footnote-1::) The first argument is the glyph to be + printed. The second argument is the distance away from the right + margin. If missing, the previously set value is used; default is + 10pt). For text lines that are too long (that is, longer than the + text length plus DIST), the margin character is directly appended + to the lines. + + With no arguments the margin character is turned off. If this + occurs before a break, no margin character is printed. + + For empty lines and lines produced by the `tl' request no margin + character is emitted. + + The margin character is associated with the current environment + (*note Environments::). + + This is quite useful for indicating text that has changed, and, in + fact, there are programs available for doing this (they are called + `nrchbar' and `changebar' and can be found in any + `comp.sources.unix' archive. + + + .ll 3i + .mc | + This paragraph is highlighted with a margin + character. + .sp + Note that vertical space isn't marked. + .br + \& + .br + But we can fake it with `\&'. + + Result: + + + This paragraph is highlighted | + with a margin character. | + + Note that vertical space isn't | + marked. | + | + But we can fake it with `\&'. | + + + - Request: .psbb filename + - Register: \n[llx] + - Register: \n[lly] + - Register: \n[urx] + - Register: \n[ury] + Retrieve the bounding box of the PostScript image found in + FILENAME. The file must conform to Adobe's "Document Structuring + Conventions" (DSC); the command searches for a `%%BoundingBox' + comment and extracts the bounding box values into the number + registers `llx', `lly', `urx', and `ury'. If an error occurs (for + example, `psbb' cannot find the `%%BoundingBox' comment), it sets + the four number registers to zero. + + +File: groff, Node: Miscellaneous-Footnotes, Up: Miscellaneous + + (1) "Margin character" is a misnomer since it is an output glyph. + + +File: groff, Node: Gtroff Internals, Next: Debugging, Prev: Miscellaneous, Up: gtroff Reference + +`gtroff' Internals +================== + + `gtroff' processes input in three steps. One or more input +characters are converted to an "input token".(1) (*note Gtroff +Internals-Footnote-1::) Then, one or more input tokens are converted +to an "output node". Finally, output nodes are converted to the +intermediate output language understood by all output devices. + + Actually, before step one happens, `gtroff' converts certain escape +sequences into reserved input characters (not accessible by the user); +such reserved characters are used for other internal processing also - +this is the very reason why not all characters are valid input. *Note +Identifiers::, for more on this topic. + + For example, the input string `fi\[:u]' is converted into a +character token `f', a character token `i', and a special token `:u' +(representing u umlaut). Later on, the character tokens `f' and `i' +are merged to a single output node representing the ligature glyph `fi' +(provided the current font has a glyph for this ligature); the same +happens with `:u'. All output glyph nodes are `processed' which means +that they are invariably associated with a given font, font size, +advance width, etc. During the formatting process, `gtroff' itself +adds various nodes to control the data flow. + + Macros, diversions, and strings collect elements in two chained +lists: a list of input tokens which have been passed unprocessed, and a +list of output nodes. Consider the following the diversion. + + + .di xxx + a + \!b + c + .br + .di + +It contains these elements. + +node list token list element number +line start node -- 1 +glyph node `a' -- 2 +word space node -- 3 +-- `b' 4 +-- `\n' 5 +glyph node `c' -- 6 +vertical size node -- 7 +vertical size node -- 8 +-- `\n' 9 + +Elements 1, 7, and 8 are inserted by `gtroff'; the latter two (which +are always present) specify the vertical extent of the last line, +possibly modified by `\x'. The `br' request finishes the current +partial line, inserting a newline input token which is subsequently +converted to a space when the diversion is reread. Note that the word +space node has a fixed width which isn't stretchable anymore. To +convert horizontal space nodes back to input tokens, use the `unformat' +request. + + Macros only contain elements in the token list (and the node list is +empty); diversions and strings can contain elements in both lists. + + Note that the `chop' request simply reduces the number of elements +in a macro, string, or diversion by one. Exceptions are "compatibility +save" and "compatibility ignore" input tokens which are ignored. The +`substring' request also ignores those input tokens. + + Some requests like `tr' or `cflags' work on glyph identifiers only; +this means that the associated glyph can be changed without destroying +this association. This can be very helpful for substituting glyphs. +In the following example, we assume that glyph `foo' isn't available by +default, so we provide a substitution using the `fchar' request and map +it to input character `x'. + + + .fchar \[foo] foo + .tr x \[foo] + +Now let us assume that we install an additional special font `bar' +which has glyph `foo'. + + + .special bar + .rchar \[foo] + +Since glyphs defined with `fchar' are searched before glyphs in special +fonts, we must call `rchar' to remove the definition of the fallback +glyph. Anyway, the translation is still active; `x' now maps to the +real glyph `foo'. + + +File: groff, Node: Gtroff Internals-Footnotes, Up: Gtroff Internals + + (1) Except the escapes `\f', `\F', `\H', `\m', `\M', `\R', `\s', and +`\S' which are processed immediately if not in copy-in mode. + + +File: groff, Node: Debugging, Next: Implementation Differences, Prev: Gtroff Internals, Up: gtroff Reference + +Debugging +========= + + `gtroff' is not easy to debug, but there are some useful features +and strategies for debugging. + + - Request: .lf line filename + Change the line number and the file name `gtroff' shall use for + error and warning messages. LINE is the input line number of the + _next_ line. + + Without argument, the request is ignored. + + This is a debugging aid for documents which are split into many + files, then put together with `soelim' and other preprocessors. + Usually, it isn't invoked manually. + + - Request: .tm string + - Request: .tm1 string + - Request: .tmc string + Send STRING to the standard error output; this is very useful for + printing debugging messages among other things. + + STRING is read in copy mode. + + The `tm' request ignores leading spaces of STRING; `tm1' handles + its argument similar to the `ds' request: a leading double quote + in STRING is stripped to allow initial blanks. + + The `tmc' request is similar to `tm1' but does not append a + newline (as is done in `tm' and `tm1'). + + - Request: .ab [string] + Similar to the `tm' request, except that it causes `gtroff' to + stop processing. With no argument it prints `User Abort.' to + standard error. + + - Request: .ex + The `ex' request also causes `gtroff' to stop processing; see also + *Note I/O::. + + When doing something involved it is useful to leave the debugging +statements in the code and have them turned on by a command line flag. + + + .if \n(DB .tm debugging output + +To activate these statements say + + + groff -rDB=1 file + + If it is known in advance that there will be many errors and no +useful output, `gtroff' can be forced to suppress formatted output with +the `-z' flag. + + - Request: .pm + Print the entire symbol table on `stderr'. Names of all defined + macros, strings, and diversions are print together with their size + in bytes. Since `gtroff' sometimes adds nodes by itself, the + returned size can be larger than expected. + + This request differs from UNIX `troff': `gtroff' reports the sizes + of diversions, ignores an additional argument to print only the + total of the sizes, and the size isn't returned in blocks of 128 + characters. + + - Request: .pnr + Print the names and contents of all currently defined number + registers on `stderr'. + + - Request: .ptr + Print the names and positions of all traps (not including input + line traps and diversion traps) on `stderr'. Empty slots in the + page trap list are printed as well, because they can affect the + priority of subsequently planted traps. + + - Request: .fl + Instruct `gtroff' to flush its output immediately. The intent is + for interactive use, but this behaviour is currently not + implemented in `gtroff'. Contrary to UNIX `troff', TTY output is + sent to a device driver also (`grotty'), making it non-trivial to + communicate interactively. + + This request causes a line break. + + - Request: .backtrace + Print a backtrace of the input stack to the standard error stream. + + Consider the following in file `test': + + + .de xxx + . backtrace + .. + .de yyy + . xxx + .. + . + .yyy + + On execution, `gtroff' prints the following: + + + test:2: backtrace: macro `xxx' + test:5: backtrace: macro `yyy' + test:8: backtrace: file `test' + + The option `-b' of `gtroff' internally calls a variant of this + request on each error and warning. + + - Register: \n[slimit] + Use the `slimit' number register to set the maximum number of + objects on the input stack. If `slimit' is less than or equal + to 0, there is no limit set. With no limit, a buggy recursive + macro can exhaust virtual memory. + + The default value is 1000; this is a compile-time constant. + + - Request: .warnscale si + Set the scaling indicator used in warnings to SI. Valid values for + SI are `u', `i', `c', `p', and `P'. At startup, it is set to `i'. + + - Request: .spreadwarn [limit] + Make `gtroff' emit a warning if the additional space inserted for + each space between words in an output line is larger or equal to + LIMIT. A negative value is changed to zero; no argument toggles + the warning on and off without changing LIMIT. The default scaling + indicator is `m'. At startup, `spreadwarn' is deactivated, and + LIMIT is set to 3m. + + For example, + + + .spreadwarn 0.2m + + will cause a warning if `gtroff' must add 0.2m or more for each + interword space in a line. + + This request is active only if text is justified to both margins + (using `.ad b'). + + `gtroff' has command line options for printing out more warnings +(`-w') and for printing backtraces (`-b') when a warning or an error +occurs. The most verbose level of warnings is `-ww'. + + - Request: .warn [flags] + - Register: \n[.warn] + Control the level of warnings checked for. The FLAGS are the sum + of the numbers associated with each warning that is to be enabled; + all other warnings are disabled. The number associated with each + warning is listed below. For example, `.warn 0' disables all + warnings, and `.warn 1' disables all warnings except that about + missing glyphs. If no argument is given, all warnings are enabled. + + The read-only number register `.warn' contains the current warning + level. + +* Menu: + +* Warnings:: + + +File: groff, Node: Warnings, Prev: Debugging, Up: Debugging + +Warnings +-------- + + The warnings that can be given to `gtroff' are divided into the +following categories. The name associated with each warning is used by +the `-w' and `-W' options; the number is used by the `warn' request and +by the `.warn' register. + +`char' +`1' + Non-existent glyphs.(1) (*note Warnings-Footnote-1::) This is + enabled by default. + +`number' +`2' + Invalid numeric expressions. This is enabled by default. *Note + Expressions::. + +`break' +`4' + In fill mode, lines which could not be broken so that their length + was less than the line length. This is enabled by default. + +`delim' +`8' + Missing or mismatched closing delimiters. + +`el' +`16' + Use of the `el' request with no matching `ie' request. *Note + if-else::. + +`scale' +`32' + Meaningless scaling indicators. + +`range' +`64' + Out of range arguments. + +`syntax' +`128' + Dubious syntax in numeric expressions. + +`di' +`256' + Use of `di' or `da' without an argument when there is no current + diversion. + +`mac' +`512' + Use of undefined strings, macros and diversions. When an undefined + string, macro, or diversion is used, that string is automatically + defined as empty. So, in most cases, at most one warning is given + for each name. + +`reg' +`1024' + Use of undefined number registers. When an undefined number + register is used, that register is automatically defined to have a + value of 0. So, in most cases, at most one warning is given for + use of a particular name. + +`tab' +`2048' + Use of a tab character where a number was expected. + +`right-brace' +`4096' + Use of `\}' where a number was expected. + +`missing' +`8192' + Requests that are missing non-optional arguments. + +`input' +`16384' + Invalid input characters. + +`escape' +`32768' + Unrecognized escape sequences. When an unrecognized escape + sequence `\X' is encountered, the escape character is ignored, and + X is printed. + +`space' +`65536' + Missing space between a request or macro and its argument. This + warning is given when an undefined name longer than two characters + is encountered, and the first two characters of the name make a + defined name. The request or macro is not invoked. When this + warning is given, no macro is automatically defined. This is + enabled by default. This warning never occurs in compatibility + mode. + +`font' +`131072' + Non-existent fonts. This is enabled by default. + +`ig' +`262144' + Invalid escapes in text ignored with the `ig' request. These are + conditions that are errors when they do not occur in ignored text. + +`color' +`524288' + Color related warnings. + +`all' + All warnings except `di', `mac' and `reg'. It is intended that + this covers all warnings that are useful with traditional macro + packages. + +`w' + All warnings. + + +File: groff, Node: Warnings-Footnotes, Up: Warnings + + (1) `char' is a misnomer since it reports missing glyphs - there +aren't missing input characters, only invalid ones. + + +File: groff, Node: Implementation Differences, Prev: Debugging, Up: gtroff Reference + +Implementation Differences +========================== + + GNU `troff' has a number of features which cause incompatibilities +with documents written with old versions of `troff'. + + Long names cause some incompatibilities. UNIX `troff' interprets + + + .dsabcd + +as defining a string `ab' with contents `cd'. Normally, GNU `troff' +interprets this as a call of a macro named `dsabcd'. Also UNIX `troff' +interprets `\*[' or `\n[' as references to a string or number register +called `['. In GNU `troff', however, this is normally interpreted as +the start of a long name. In compatibility mode GNU `troff' interprets +long names in the traditional way (which means that they are not +recognized as names). + + - Request: .cp [n] + - Request: .do cmd + - Register: \n[.C] + If N is missing or non-zero, turn on compatibility mode; + otherwise, turn it off. + + The read-only number register `.C' is 1 if compatibility mode is + on, 0 otherwise. + + Compatibility mode can be also turned on with the `-C' command line + option. + + The `do' request turns off compatibility mode while executing its + arguments as a `gtroff' command. + + + .do fam T + + executes the `fam' request when compatibility mode is enabled. + + `gtroff' restores the previous compatibility setting before + interpreting any files sourced by the CMD. + + Two other features are controlled by `-C'. If not in compatibility +mode, GNU `troff' preserves the input level in delimited arguments: + + + .ds xx ' + \w'abc\*(xxdef' + +In compatibility mode, the string `72def'' is returned; without `-C' +the resulting string is `168' (assuming a TTY output device). + + Finally, the escapes `\f', `\H', `\m', `\M', `\R', `\s', and `\S' +are transparent for recognizing the beginning of a line only in +compatibility mode (this is a rather obscure feature). For example, +the code + + + .de xx + Hallo! + .. + \fB.xx\fP + + prints `Hallo!' in bold face if in compatibility mode, and `.xx' in +bold face otherwise. + + GNU `troff' does not allow the use of the escape sequences `\|', +`\^', `\&', `\{', `\}', `\<SP>', `\'', `\`', `\-', `\_', `\!', `\%', +and `\c' in names of strings, macros, diversions, number registers, +fonts or environments; UNIX `troff' does. The `\A' escape sequence +(*note Identifiers::) may be helpful in avoiding use of these escape +sequences in names. + + Fractional point sizes cause one noteworthy incompatibility. In +UNIX `troff' the `ps' request ignores scale indicators and thus + + + .ps 10u + +sets the point size to 10 points, whereas in GNU `troff' it sets the +point size to 10 scaled points. *Note Fractional Type Sizes::, for +more information. + + In GNU `troff' there is a fundamental difference between +(unformatted) input characters and (formatted) output glyphs. +Everything that affects how a glyph is output is stored with the glyph +node; once a glyph node has been constructed it is unaffected by any +subsequent requests that are executed, including `bd', `cs', `tkf', +`tr', or `fp' requests. Normally glyphs are constructed from input +characters at the moment immediately before the glyph is added to the +current output line. Macros, diversions and strings are all, in fact, +the same type of object; they contain lists of input characters and +glyph nodes in any combination. A glyph node does not behave like an +input character for the purposes of macro processing; it does not +inherit any of the special properties that the input character from +which it was constructed might have had. For example, + + + .di x + \\\\ + .br + .di + .x + +prints `\\' in GNU `troff'; each pair of input backslashes is turned +into one output backslash and the resulting output backslashes are not +interpreted as escape characters when they are reread. UNIX `troff' +would interpret them as escape characters when they were reread and +would end up printing one `\'. The correct way to obtain a printable +backslash is to use the `\e' escape sequence: This always prints a +single instance of the current escape character, regardless of whether +or not it is used in a diversion; it also works in both GNU `troff' and +UNIX `troff'.(1) (*note Implementation Differences-Footnote-1::) To +store, for some reason, an escape sequence in a diversion that will be +interpreted when the diversion is reread, either use the traditional +`\!' transparent output facility, or, if this is unsuitable, the new +`\?' escape sequence. + + *Note Diversions::, and *Note Gtroff Internals::, for more +information. + + +File: groff, Node: Implementation Differences-Footnotes, Up: Implementation Differences + + (1) To be completely independent of the current escape character, +use `\(rs' which represents a reverse solidus (backslash) glyph. + + +File: groff, Node: Preprocessors, Next: Output Devices, Prev: gtroff Reference, Up: Top + +Preprocessors +************* + + This chapter describes all preprocessors that come with `groff' or +which are freely available. + +* Menu: + +* geqn:: +* gtbl:: +* gpic:: +* ggrn:: +* grap:: +* grefer:: +* gsoelim:: + + +File: groff, Node: geqn, Next: gtbl, Prev: Preprocessors, Up: Preprocessors + +`geqn' +====== + +* Menu: + +* Invoking geqn:: + + +File: groff, Node: Invoking geqn, Prev: geqn, Up: geqn + +Invoking `geqn' +--------------- + + +File: groff, Node: gtbl, Next: gpic, Prev: geqn, Up: Preprocessors + +`gtbl' +====== + +* Menu: + +* Invoking gtbl:: + + +File: groff, Node: Invoking gtbl, Prev: gtbl, Up: gtbl + +Invoking `gtbl' +--------------- + + +File: groff, Node: gpic, Next: ggrn, Prev: gtbl, Up: Preprocessors + +`gpic' +====== + +* Menu: + +* Invoking gpic:: + + +File: groff, Node: Invoking gpic, Prev: gpic, Up: gpic + +Invoking `gpic' +--------------- + + +File: groff, Node: ggrn, Next: grap, Prev: gpic, Up: Preprocessors + +`ggrn' +====== + +* Menu: + +* Invoking ggrn:: + + +File: groff, Node: Invoking ggrn, Prev: ggrn, Up: ggrn + +Invoking `ggrn' +--------------- + + +File: groff, Node: grap, Next: grefer, Prev: ggrn, Up: Preprocessors + +`grap' +====== + + A free implementation of `grap', written by Ted Faber, is available +as an extra package from the following address: + + <http://www.lunabase.org/~faber/Vault/software/grap/> + + +File: groff, Node: grefer, Next: gsoelim, Prev: grap, Up: Preprocessors + +`grefer' +======== + +* Menu: + +* Invoking grefer:: + + +File: groff, Node: Invoking grefer, Prev: grefer, Up: grefer + +Invoking `grefer' +----------------- + + +File: groff, Node: gsoelim, Prev: grefer, Up: Preprocessors + +`gsoelim' +========= + +* Menu: + +* Invoking gsoelim:: + + +File: groff, Node: Invoking gsoelim, Prev: gsoelim, Up: gsoelim + +Invoking `gsoelim' +------------------ + + +File: groff, Node: Output Devices, Next: File formats, Prev: Preprocessors, Up: Top + +Output Devices +************** + +* Menu: + +* Special Characters:: +* grotty:: +* grops:: +* grodvi:: +* grolj4:: +* grolbp:: +* grohtml:: +* gxditview:: + + +File: groff, Node: Special Characters, Next: grotty, Prev: Output Devices, Up: Output Devices + +Special Characters +================== + + *Note Font Files::. + + +File: groff, Node: grotty, Next: grops, Prev: Special Characters, Up: Output Devices + +`grotty' +======== + +* Menu: + +* Invoking grotty:: + + +File: groff, Node: Invoking grotty, Prev: grotty, Up: grotty + +Invoking `grotty' +----------------- + |
