diff options
Diffstat (limited to 'contrib/groff/doc/groff-7')
| -rw-r--r-- | contrib/groff/doc/groff-7 | 1460 |
1 files changed, 0 insertions, 1460 deletions
diff --git a/contrib/groff/doc/groff-7 b/contrib/groff/doc/groff-7 deleted file mode 100644 index edf7290..0000000 --- a/contrib/groff/doc/groff-7 +++ /dev/null @@ -1,1460 +0,0 @@ -This is groff, produced by makeinfo version 4.3d from ./groff.texinfo. - -This manual documents GNU `troff' version 1.19. - - Copyright (C) 1994-2000, 2001, 2002, 2003 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 Typesetting -START-INFO-DIR-ENTRY -* Groff: (groff). The GNU troff document formatting system. -END-INFO-DIR-ENTRY - - -File: groff, Node: Page Location Traps, Next: Diversion Traps, Prev: Traps, Up: Traps - -Page Location Traps -------------------- - - "Page location traps" perform an action when `gtroff' reaches or -passes a certain vertical location on the page. Page location traps -have a variety of purposes, including: - - * setting headers and footers - - * setting body text in multiple columns - - * setting footnotes - - - Request: .vpt flag - - Register: \n[.vpt] - Enable vertical position traps if FLAG is non-zero, or disables - them otherwise. Vertical position traps are traps set by the `wh' - or `dt' requests. Traps set by the `it' request are not vertical - position traps. The parameter that controls whether vertical - position traps are enabled is global. Initially vertical position - traps are enabled. The current setting of this is available in the - `.vpt' read-only number register. - - Note that a page can't be ejected if `vpt' is set to zero. - - - Request: .wh dist [macro] - Set a page location trap. Non-negative values for DIST set the - trap relative to the top of the page; negative values set the trap - relative to the bottom of the page. Default scaling indicator is - `v'. - - MACRO is the name of the macro to execute when the trap is sprung. - If MACRO is missing, remove the first trap (if any) at DIST. - - The following is a simple example of how many macro packages set - headers and footers. - - - .de hd \" Page header - ' sp .5i - . tl 'Title''date' - ' sp .3i - .. - . - .de fo \" Page footer - ' sp 1v - . tl ''%'' - ' bp - .. - . - .wh 0 hd \" trap at top of the page - .wh -1i fo \" trap one inch from bottom - - A trap at or below the bottom of the page is ignored; it can be - made active by either moving it up or increasing the page length - so that the trap is on the page. - - It is possible to have more than one trap at the same location; to - do so, the traps must be defined at different locations, then - moved together with the `ch' request; otherwise the second trap - would replace the first one. Earlier defined traps hide later - defined traps if moved to the same position (the many empty lines - caused by the `bp' request are omitted in the following example): - - - .de a - . nop a - .. - .de b - . nop b - .. - .de c - . nop c - .. - . - .wh 1i a - .wh 2i b - .wh 3i c - .bp - => a b c - - - .ch b 1i - .ch c 1i - .bp - => a - - - .ch a 0.5i - .bp - => a b - - - - Register: \n[.t] - A read-only number register holding the distance to the next trap. - - If there are no traps between the current position and the bottom - of the page, it contains the distance to the page bottom. In a - diversion, the distance to the page bottom is infinite (the - returned value is the biggest integer which can be represented in - `groff') if there are no diversion traps. - - - Request: .ch macro [dist] - Change the location of a trap. The first argument is the name of - the macro to be invoked at the trap, and the second argument is - the new location for the trap (note that the parameters are - specified in opposite order as in the `wh' request). This is - useful for building up footnotes in a diversion to allow more - space at the bottom of the page for them. - - Default scaling indicator for DIST is `v'. If DIST is missing, - the trap is removed. - - - - Register: \n[.ne] - The read-only number register `.ne' contains the amount of space - that was needed in the last `ne' request that caused a trap to be - sprung. Useful in conjunction with the `.trunc' register. *Note - Page Control::, for more information. - - Since the `.ne' register is only set by traps it doesn't make much - sense to use it outside of trap macros. - - - Register: \n[.trunc] - A read-only register containing the amount of vertical space - truncated by the most recently sprung vertical position trap, or, - if the trap was sprung by an `ne' request, minus the amount of - vertical motion produced by the `ne' request. In other words, at - the point a trap is sprung, it represents the difference of what - the vertical position would have been but for the trap, and what - the vertical position actually is. - - Since the `.trunc' register is only set by traps and it doesn't - make much sense to use it outside of trap macros. - - - Register: \n[.pe] - A read-only register which is set to 1 while a page is ejected with - the `bp' request (or by the end of input). - - Outside of traps this register is always zero. In the following - example, only the second call to `x' is caused by `bp'. - - - .de x - \&.pe=\\n[.pe] - .br - .. - .wh 1v x - .wh 4v x - A line. - .br - Another line. - .br - => A line. - .pe=0 - Another line. - - .pe=1 - - - An important fact to consider while designing macros is that -diversions and traps do not interact normally. For example, if a trap -invokes a header macro (while outputting a diversion) which tries to -change the font on the current page, the effect will not be visible -before the diversion has completely been printed (except for input -protected with `\!' or `\?') since the data in the diversion is already -formatted. In most cases, this is not the expected behaviour. - - -File: groff, Node: Diversion Traps, Next: Input Line Traps, Prev: Page Location Traps, Up: Traps - -Diversion Traps ---------------- - - - Request: .dt dist macro - Set a trap _within_ a diversion. DIST is the location of the trap - (identical to the `wh' request; default scaling indicator is `v') - and MACRO is the name of the macro to be invoked. The number - register `.t' still works within diversions. *Note Diversions::, - for more information. - - -File: groff, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps - -Input Line Traps ----------------- - - - Request: .it n macro - - Request: .itc n macro - Set an input line trap. N is the number of lines of input which - may be read before springing the trap, MACRO is the macro to be - invoked. Request lines are not counted as input lines. - - For example, one possible use is to have a macro which prints the - next N lines in a bold font. - - - .de B - . it \\$1 B-end - . ft B - .. - . - .de B-end - . ft R - .. - - The `itc' request is identical except that an interrupted text - line (ending with `\c') is not counted as a separate line. - - Both requests are associated with the current environment (*note - Environments::); switching to another environment disables the - current input trap, and going back reactivates it, restoring the - number of already processed lines. - - -File: groff, Node: Blank Line Traps, Next: End-of-input Traps, Prev: Input Line Traps, Up: Traps - -Blank Line Traps ----------------- - - - Request: .blm macro - Set a blank line trap. `gtroff' executes MACRO when it encounters - a blank line in the input file. - - -File: groff, Node: End-of-input Traps, Prev: Blank Line Traps, Up: Traps - -End-of-input Traps ------------------- - - - Request: .em macro - Set a trap at the end of input. MACRO is executed after the last - line of the input file has been processed. - - For example, if the document had to have a section at the bottom - of the last page for someone to approve it, the `em' request could - be used. - - - .de approval - . ne 5v - . sp |(\\n[.t] - 6v) - . in +4i - . lc _ - . br - Approved:\t\a - . sp - Date:\t\t\a - .. - . - .em approval - - - -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 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. - Note that only the just processed lines are counted: For the - computation of `dn' and `dl', the requests `da' and `boxa' are - handled as if `di' and `box' had been used - lines which have been - already stored in a macro are not taken into account. - - - .\" 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. Both escapes take the given text and - "transparently" embed 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. 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[.w] - - Register: \n[.cht] - - Register: \n[.cdp] - - Register: \n[.csk] - The `\n[.w]' register contains the width of the last glyph added - to the current environment. - - The `\n[.cht]' register contains the height of the last glyph - added to the current environment. - - The `\n[.cdp]' register contains the depth of the last glyph added - to the current environment. It is positive for glyphs extending - below the baseline. - - The `\n[.csk]' register contains the "skew" (how far to the right - of the glyph's center that `gtroff' should place an accent) of the - last glyph added to the current environment. - - - Register: \n[.n] - The `\n[.n]' register contains the length of the previous output - line in 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), `cmy' (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 optionally 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. - - Note that other `troff' implementations (including the original - AT&T version) handle `lf' differently. For them, LINE changes the - line number of the _current_ line. - - - 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:: - |
