diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:44:05 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:44:05 +0000 |
| commit | d318611dd6f23fcfedd50e9b9e24620b102ba96a (patch) | |
| tree | 8b9eef82ca40fdd5a8deeabf07572074c236095d /doc/groff.info-2 | |
| parent | Initial commit. (diff) | |
| download | groff-upstream.tar.xz groff-upstream.zip | |
Adding upstream version 1.23.0.upstream/1.23.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/groff.info-2')
| -rw-r--r-- | doc/groff.info-2 | 7529 |
1 files changed, 7529 insertions, 0 deletions
diff --git a/doc/groff.info-2 b/doc/groff.info-2 new file mode 100644 index 0000000..44572a0 --- /dev/null +++ b/doc/groff.info-2 @@ -0,0 +1,7529 @@ +This is groff.info, produced by makeinfo version 7.0.3 from groff.texi. + +This manual documents GNU 'troff' version 1.23.0. + + Copyright © 1994-2023 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.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". +INFO-DIR-SECTION Typesetting +START-INFO-DIR-ENTRY +* Groff: (groff). The GNU roff document formatting system. +END-INFO-DIR-ENTRY + + +File: groff.info, Node: Selecting Fonts, Next: Font Families, Prev: Using Fonts, Up: Using Fonts + +5.19.1 Selecting Fonts +---------------------- + +We use "font" to refer to any of several means of identifying a font: by +mounting position ('3'), by abstract style ('B'), or by its identifier +('TB'). + + -- Request: .ft [font] + -- Escape sequence: \ff + -- Escape sequence: \f(fn + -- Escape sequence: \f[font] + -- Register: \n[.fn] + The 'ft' request selects the typeface FONT. If the argument is + absent or 'P', it selects the previously chosen font. If FONT is a + non-negative integer, it is interpreted as mounting position; the + font mounted there is selected. If that position refers to an + abstract style, it is combined with the default family (see 'fam' + and '\F' below) to make a resolved font name. If the mounting + position is not a style and no font is mounted there, GNU 'troff' + emits a warning in category 'font' and ignores the request. + + If FONT matches a style name, it is combined with the current + family to make a resolved font name. Otherwise, FONT is assumed to + already be a resolved font name. + + The resolved font name is subject to translation (see request 'ftr' + below). Next, the (possibly translated) font name's mounting + position is looked up; if not mounted, FONT is sought on the file + system as a font description file and, if located, automatically + mounted at the next available position (see register '.fp' below). + If the font was mounted using an identifier different from its font + description file name (see request 'fp' below), that file name is + then looked up. If a font description file for the resolved font + name is not found, GNU 'troff' emits a warning in category 'font' + and ignores the request. + + The '\f' escape sequence is similar, using one-character name (or + mounting position) F, two-character name FN, or a name FONT of + arbitrary length. '\f[]' selects the previous font. The syntax + form '\fP' is supported for backward compatibility, and '\f[P]' for + consistency. + + eggs, bacon, + .ft I + spam, + .ft + and sausage. + .br + eggs, bacon, \fIspam,\fP and sausage. + => eggs, bacon, spam, and sausage + => eggs, bacon, spam, and sausage + + The current and previously selected fonts are properties of the + environment (*note Environments::). + + The read-only string-valued register '.fn' contains the resolved + font name of the selected font. + + '\f' doesn't produce an input token in GNU 'troff'; it thus can be + used in requests that expect a single-character argument. We can + assign a font to a margin character as follows (*note + Miscellaneous::). + + .mc \f[I]x\f[] + + -- Request: .ftr f [g] + Translate font F to font G. Whenever a font named F is referred to + in a '\f' escape sequence, in the 'F' and 'S' conditional + operators, or in the 'ft', 'ul', 'bd', 'cs', 'tkf', 'special', + 'fspecial', 'fp', or 'sty' requests, font G is used. If G is + missing or equal to F the translation is undone. + + Font translations cannot be chained. + + .ftr XXX TR + .ftr XXX YYY + .ft XXX + error-> warning: can't find font 'XXX' + + -- Request: .fzoom f [zoom] + -- Register: \n[.zoom] + Set magnification of font F to factor ZOOM, which must be a + non-negative integer multiple of 1/1000th. This request is useful + to adjust the optical size of a font in relation to the others. In + the example below, font 'CR' is magnified by 10% (the zoom factor + is thus 1.1). + + .fam P + .fzoom CR 1100 + .ps 12 + Palatino and \f[CR]Courier\f[] + + A missing or zero value of ZOOM is the same as a value of 1000, + which means no magnification. F must be a resolved font name, not + an abstract style. + + The magnification of a font is completely transparent to GNU + 'troff'; a change of the zoom factor doesn't cause any effect + except that the dimensions of glyphs, (word) spaces, kerns, etc., + of the affected font are adjusted accordingly. + + The zoom factor of the current font is available in the read-only + register '.zoom', in multiples of 1/1000th. It returns zero if + there is no magnification. + + +File: groff.info, Node: Font Families, Next: Font Positions, Prev: Selecting Fonts, Up: Using Fonts + +5.19.2 Font Families +-------------------- + +To accommodate the wide variety of fonts available, GNU 'troff' +distinguishes "font families" and "font styles". A resolved font name +is the catenation of a font family and a style. Selecting an abstract +style causes GNU 'troff' to combine it with the default font family. + + You can thus compose a document using abstract styles exclusively for +its body or running text, selecting a specific family only for titles or +examples, for instance, and change the default family on the command +line (recall *note Groff Options::). + + Fonts for the devices 'ps', 'pdf', 'dvi', 'lj4', 'lbp', and the X11 +devices support this mechanism. By default, GNU 'troff' uses the Times +family with the four styles 'R', 'I', 'B', and 'BI'. + + -- Request: .fam [family] + -- Register: \n[.fam] + -- Escape sequence: \Ff + -- Escape sequence: \F(fm + -- Escape sequence: \F[family] + Set the default font family, used in combination with abstract + styles to construct a resolved font name, to FAMILY (one-character + name F, two-character name FM). If no argument is given, GNU + 'troff' selects the previous font family; if there none, is it + falls back to the device's default(1) (*note Font + Families-Footnote-1::) or its own ('T'). + + The '\F' escape sequence works similarly. In disanalogy to '\f', + '\FP' makes 'P' the default family. Use '\F[]' to select the + previous default family. The default font family is available in + the read-only string-valued register '.fam'; it is associated with + the environment (*note Environments::). + + spam, \" startup defaults are T (Times) R (roman) + .fam H \" make Helvetica the default family + spam, \" family H + style R = HR + .ft B \" family H + style B = HB + spam, + .ft CR \" Courier roman (default family not changed) + spam, + .ft \" back to Helvetica bold + spam, + .fam T \" make Times the default family + spam, \" family T + style B = TB + .ft AR \" font AR (not a style) + baked beans, + .ft R \" family T + style R = TR + and spam. + + '\F' doesn't produce an input token in GNU 'troff'. As a + consequence, it can be used in requests like 'mc' (which expects a + single character as an argument) to change the font family on the + fly. + + .mc \F[P]x\F[] + + -- Request: .sty n style + -- Register: \n[.sty] + Associate an abstract style STYLE with mounting position N, which + must be a non-negative integer. If the requests 'cs', 'bd', 'tkf', + 'uf', or 'fspecial' are applied to an abstract style, they are + instead applied to the member of the current family corresponding + to that style. + + The default family can be set with the '-f' option (*note Groff + Options::). The 'styles' command in the 'DESC' file controls which + font positions (if any) are initially associated with abstract + styles rather than fonts. + + *Caution:* The STYLE argument is not validated. Errors may occur + later, when the formatter attempts to construct a resolved font + name, or format a character for output. + + .nr BarPos \n[.fp] + .sty \n[.fp] Bar + .fam Foo + .ft \n[BarPos] + .tm .f=\n[.f] + A + error-> error: no font family named 'Foo' exists + error-> .f=41 + error-> error: cannot format glyph: no current font + + When an abstract style has been selected, the read-only + string-valued register '.sty' interpolates its name; this datum is + associated with the environment (*note Environments::). Otherwise, + '.sty' interpolates nothing. + + +File: groff.info, Node: Font Families-Footnotes, Up: Font Families + + (1) *Note DESC File Format::. + + +File: groff.info, Node: Font Positions, Next: Using Symbols, Prev: Font Families, Up: Using Fonts + +5.19.3 Font Positions +--------------------- + +To support typeface indirection through abstract styles, and for +compatibility with AT&T 'troff', the formatter maintains a list of font +"positions" at which fonts required by a document are "mounted". An +output device's description file 'DESC' typically configures a set of +pre-mounted fonts; see *note Device and Font Description Files::. A +font need not be explicitly mounted before it is selected; GNU 'troff' +will search 'GROFF_FONT_PATH' for it by name and mount it at the first +free mounting position on demand. + + -- Request: .fp pos id [font-description-file-name] + -- Register: \n[.f] + -- Register: \n[.fp] + Mount a font under the name ID at mounting position POS, a + non-negative integer. When the formatter starts up, it reads the + output device's description to mount an initial set of faces, and + selects font position 1. Position 0 is unused by default. Unless + the FONT-DESCRIPTION-FILE-NAME argument is given, ID should be the + name of a font description file stored in a directory corresponding + to the selected output device. GNU 'troff' does not traverse + directories to locate the font description file. + + The optional third argument enables font names to be aliased, which + can be necessary in compatibility mode since AT&T 'troff' syntax + affords no means of identifying fonts with names longer than two + characters, like 'TBI' or 'ZCMI', in a font selection escape + sequence. *Note Compatibility Mode::. You can also alias fonts on + mounting for convenience or abstraction. (See below regarding the + '.fp' register.) + + .fp \n[.fp] SC ZCMI + Send a \f(SChand-written\fP thank-you note. + .fp \n[.fp] Emph TI + .fp \n[.fp] Strong TB + Are \f[Emph]these names\f[] \f[Strong]comfortable\f[]? + + 'DESC', 'P', and non-negative integers are not usable as font + identifiers. + + The position of the currently selected font (or abstract style) is + available in the read-only register '.f'. It is associated with + the environment (*note Environments::). + + You can copy the value of '.f' to another register to save it for + later use. + + .nr saved-font \n[.f] + ... text involving many font changes ... + .ft \n[saved-font] + + The index of the next (non-zero) free font position is available in + the read-only register '.fp'. Fonts not listed in the 'DESC' file + are automatically mounted at position '\n[.fp]' when selected with + the 'ft' request or '\f' escape sequence. When mounting a font at + a position explicitly with the 'fp' request, this same practice + should be followed, although GNU 'troff' does not enforce this + strictly. + + +File: groff.info, Node: Using Symbols, Next: Character Classes, Prev: Font Positions, Up: Using Fonts + +5.19.4 Using Symbols +-------------------- + +A "glyph" is a graphical representation of a "character". While a +character is an abstraction of semantic information, a glyph is +something that can be seen on screen or paper. A character has many +possible representation forms (for example, the character 'A' can be +written in an upright or slanted typeface, producing distinct glyphs). +Sometimes, a sequence of characters map to a single glyph: this is a +"ligature"--the most common is 'fi'. + + Space characters never become glyphs in GNU 'troff'. If not +discarded (as when trailing on text lines), they are represented by +horizontal motions in the output. + + A "symbol" is simply a named glyph. Within 'gtroff', all glyph names +of a particular font are defined in its font file. If the user requests +a glyph not available in this font, 'gtroff' looks up an ordered list of +"special fonts". By default, the PostScript output device supports the +two special fonts 'SS' (slanted symbols) and 'S' (symbols) (the former +is looked up before the latter). Other output devices use different +names for special fonts. Fonts mounted with the 'fonts' keyword in the +'DESC' file are globally available. To install additional special fonts +locally (i.e., for a particular font), use the 'fspecial' request. + + Here are the exact rules how 'gtroff' searches a given symbol: + + * If the symbol has been defined with the 'char' request, use it. + This hides a symbol with the same name in the current font. + + * Check the current font. + + * If the symbol has been defined with the 'fchar' request, use it. + + * Check whether the current font has a font-specific list of special + fonts; test all fonts in the order of appearance in the last + 'fspecial' call if appropriate. + + * If the symbol has been defined with the 'fschar' request for the + current font, use it. + + * Check all fonts in the order of appearance in the last 'special' + call. + + * If the symbol has been defined with the 'schar' request, use it. + + * As a last resort, consult all fonts loaded up to now for special + fonts and check them, starting with the lowest font number. This + can sometimes lead to surprising results since the 'fonts' line in + the 'DESC' file often contains empty positions, which are filled + later on. For example, consider the following: + + fonts 3 0 0 FOO + + This mounts font 'foo' at font position 3. We assume that 'FOO' is + a special font, containing glyph 'foo', and that no font has been + loaded yet. The line + + .fspecial BAR BAZ + + makes font 'BAZ' special only if font 'BAR' is active. We further + assume that 'BAZ' is really a special font, i.e., the font + description file contains the 'special' keyword, and that it also + contains glyph 'foo' with a special shape fitting to font 'BAR'. + After executing 'fspecial', font 'BAR' is loaded at font + position 1, and 'BAZ' at position 2. + + We now switch to a new font 'XXX', trying to access glyph 'foo' + that is assumed to be missing. There are neither font-specific + special fonts for 'XXX' nor any other fonts made special with the + 'special' request, so 'gtroff' starts the search for special fonts + in the list of already mounted fonts, with increasing font + positions. Consequently, it finds 'BAZ' before 'FOO' even for + 'XXX', which is not the intended behaviour. + + *Note Device and Font Description Files::, and *note Special Fonts::, +for more details. + + The 'groff_char(7)' man page houses a complete list of predefined +special character names, but the availability of any as a glyph is +device- and font-dependent. For example, say + + man -Tdvi groff_char > groff_char.dvi + +to obtain those available with the DVI device and default font +configuration.(1) (*note Using Symbols-Footnote-1::) If you want to use +an additional macro package to change the fonts used, 'groff' (or +'gtroff') must be run directly. + + groff -Tdvi -mec -man groff_char.7 > groff_char.dvi + + Special character names not listed in 'groff_char(7)' are derived +algorithmically, using a simplified version of the Adobe Glyph List +(AGL) algorithm, which is described in +<https://github.com/adobe-type-tools/agl-aglfn>. The (frozen) set of +names that can't be derived algorithmically is called the "'groff' glyph +list (GGL)". + + * A glyph for Unicode character U+XXXX[X[X]], which is not a + composite character is named 'uXXXX[X[X]]'. X must be an uppercase + hexadecimal digit. Examples: 'u1234', 'u008E', 'u12DB8'. The + largest Unicode value is 0x10FFFF. There must be at least four 'X' + digits; if necessary, add leading zeroes (after the 'u'). No zero + padding is allowed for character codes greater than 0xFFFF. + Surrogates (i.e., Unicode values greater than 0xFFFF represented + with character codes from the surrogate area U+D800-U+DFFF) are not + allowed either. + + * A glyph representing more than a single input character is named + + 'u' COMPONENT1 '_' COMPONENT2 '_' COMPONENT3 ... + + Example: 'u0045_0302_0301'. + + For simplicity, all Unicode characters that are composites must be + maximally decomposed to NFD;(2) (*note Using Symbols-Footnote-2::) + for example, 'u00CA_0301' is not a valid glyph name since U+00CA + (LATIN CAPITAL LETTER E WITH CIRCUMFLEX) can be further decomposed + into U+0045 (LATIN CAPITAL LETTER E) and U+0302 (COMBINING + CIRCUMFLEX ACCENT). 'u0045_0302_0301' is thus the glyph name for + U+1EBE, LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE. + + * groff maintains a table to decompose all algorithmically derived + glyph names that are composites itself. For example, 'u0100' + (LATIN LETTER A WITH MACRON) is automatically decomposed into + 'u0041_0304'. Additionally, a glyph name of the GGL is preferred + to an algorithmically derived glyph name; 'groff' also + automatically does the mapping. Example: The glyph 'u0045_0302' is + mapped to '^E'. + + * glyph names of the GGL can't be used in composite glyph names; for + example, '^E_u0301' is invalid. + + -- Escape sequence: \(nm + -- Escape sequence: \[name] + -- Escape sequence: \[base-glyph combining-component ...] + Typeset a special character NAME (two-character name NM) or a + composite glyph consisting of BASE-GLYPH overlaid with one or more + COMBINING-COMPONENTs. For example, '\[A ho]' is a capital letter + "A" with a "hook accent" (ogonek). + + There is no special syntax for one-character names--the analogous + form '\N' would collide with other escape sequences. However, the + four escape sequences '\'', '\-', '\_', and '\`', are translated on + input to the special character escape sequences '\[aa]', '\[-]', + '\[ul]', and '\[ga]', respectively. + + A special character name of length one is not the same thing as an + ordinary character: that is, the character 'a' is not the same as + '\[a]'. + + If NAME is undefined, a warning in category 'char' is produced and + the escape is ignored. *Note Warnings::, for information about the + enablement and suppression of warnings. + + GNU 'troff' resolves '\[...]' with more than a single component as + follows: + + * Any component that is found in the GGL is converted to the + 'uXXXX' form. + + * Any component 'uXXXX' that is found in the list of + decomposable glyphs is decomposed. + + * The resulting elements are then concatenated with '_' in + between, dropping the leading 'u' in all elements but the + first. + + No check for the existence of any component (similar to 'tr' + request) is done. + + Examples: + + '\[A ho]' + 'A' maps to 'u0041', 'ho' maps to 'u02DB', thus the final + glyph name would be 'u0041_02DB'. This is not the expected + result: the ogonek glyph 'ho' is a spacing ogonek, but for a + proper composite a non-spacing ogonek (U+0328) is necessary. + Looking into the file 'composite.tmac', one can find + '.composite ho u0328', which changes the mapping of 'ho' while + a composite glyph name is constructed, causing the final glyph + name to be 'u0041_0328'. + + '\[^E u0301]' + '\[^E aa]' + '\[E a^ aa]' + '\[E ^ ']' + '^E' maps to 'u0045_0302', thus the final glyph name is + 'u0045_0302_0301' in all forms (assuming proper calls of the + 'composite' request). + + It is not possible to define glyphs with names like 'A ho' within a + 'groff' font file. This is not really a limitation; instead, you + have to define 'u0041_0328'. + + -- Escape sequence: \C'xxx' + Typeset the glyph of the special character XXX. Normally, it is + more convenient to use '\[XXX]', but '\C' has some advantages: it + is compatible with AT&T device-independent 'troff' (and therefore + available in compatibility mode(3) (*note Using + Symbols-Footnote-3::)) and can interpolate special characters with + ']' in their names. The delimiter need not be a neutral + apostrophe; see *note Delimiters::. + + -- Request: .composite id1 id2 + Map special character name ID1 to ID2 if ID1 is used in '\[...]' + with more than one component. See above for examples. This is a + strict rewriting of the special character name; no check is + performed for the existence of a glyph for either. A set of + default mappings for many accents can be found in the file + 'composite.tmac', loaded by the default 'troffrc' at startup. + + -- Escape sequence: \N'n' + Typeset the glyph with code N in the current font ('n' is _not_ the + input character code). The number N can be any non-negative + decimal integer. Most devices only have glyphs with codes between + 0 and 255; the Unicode output device uses codes in the range + 0-65535. If the current font does not contain a glyph with that + code, special fonts are _not_ searched. The '\N' escape sequence + can be conveniently used in conjunction with the 'char' request: + + .char \[phone] \f[ZD]\N'37' + + The code of each glyph is given in the fourth column in the font + description file after the 'charset' command. It is possible to + include unnamed glyphs in the font description file by using a name + of '---'; the '\N' escape sequence is the only way to use these. + + No kerning is applied to glyphs accessed with '\N'. The delimiter + need not be a neutral apostrophe; see *note Delimiters::. + + A few escape sequences are also special characters. + + -- Escape sequence: \' + An escaped neutral apostrophe is a synonym for '\[aa]' (acute + accent). + + -- Escape sequence: \` + An escaped grave accent is a synonym for '\[ga]' (grave accent). + + -- Escape sequence: \- + An escaped hyphen-minus is a synonym for '\[-]' (minus sign). + + -- Escape sequence: \_ + An escaped underscore ("low line") is a synonym for '\[ul]' + (underrule). On typesetting devices, the underrule is + font-invariant and drawn lower than the underscore '_'. + + -- Request: .cflags n c1 c2 ... + Assign properties encoded by the number N to characters C1, C2, and + so on. + + Input characters, including special characters introduced by an + escape, have certain properties associated with them.(4) (*note + Using Symbols-Footnote-4::) These properties can be modified with + this request. The first argument is the sum of the desired flags + and the remaining arguments are the characters to be assigned those + properties. Spaces between the CN arguments are optional. Any + argument CN can be a character class defined with the 'class' + request rather than an individual character. *Note Character + Classes::. + + The non-negative integer N is the sum of any of the following. + Some combinations are nonsensical, such as '33' (1 + 32). + + '1' + Recognize the character as ending a sentence if followed by a + newline or two spaces. Initially, characters '.?!' have this + property. + + '2' + Enable breaks before the character. A line is not broken at a + character with this property unless the characters on each + side both have non-zero hyphenation codes. This exception can + be overridden by adding 64. Initially, no characters have + this property. + + '4' + Enable breaks after the character. A line is not broken at a + character with this property unless the characters on each + side both have non-zero hyphenation codes. This exception can + be overridden by adding 64. Initially, characters + '\-\[hy]\[em]' have this property. + + '8' + Mark the glyph associated with this character as overlapping + other instances of itself horizontally. Initially, characters + '\[ul]\[rn]\[ru]\[radicalex]\[sqrtex]' have this property. + + '16' + Mark the glyph associated with this character as overlapping + other instances of itself vertically. Initially, the + character '\[br]' has this property. + + '32' + Mark the character as transparent for the purpose of + end-of-sentence recognition. In other words, an + end-of-sentence character followed by any number of characters + with this property is treated as the end of a sentence if + followed by a newline or two spaces. This is the same as + having a zero space factor in TeX. Initially, characters + '"')]*\[dg]\[dd]\[rq]\[cq]' have this property. + + '64' + Ignore hyphenation codes of the surrounding characters. Use + this in combination with values 2 and 4 (initially, no + characters have this property). + + For example, if you need an automatic break point after the + en-dash in numeric ranges like "3000-5000", insert + + .cflags 68 \[en] + + into your document. However, this practice can lead to bad + layout if done thoughtlessly; in most situations, a better + solution instead of changing the 'cflags' value is to insert + '\:' right after the hyphen at the places that really need a + break point. + + The remaining values were implemented for East Asian language + support; those who use alphabetic scripts exclusively can disregard + them. + + '128' + Prohibit a line break before the character, but allow a line + break after the character. This works only in combination + with flags 256 and 512 and has no effect otherwise. + Initially, no characters have this property. + + '256' + Prohibit a line break after the character, but allow a line + break before the character. This works only in combination + with flags 128 and 512 and has no effect otherwise. + Initially, no characters have this property. + + '512' + Allow line break before or after the character. This works + only in combination with flags 128 and 256 and has no effect + otherwise. Initially, no characters have this property. + + In contrast to values 2 and 4, the values 128, 256, and 512 work + pairwise. If, for example, the left character has value 512, and + the right character 128, no break will be automatically inserted + between them. If we use value 6 instead for the left character, a + break after the character can't be suppressed since the neighboring + character on the right doesn't get examined. + + -- Request: .char c [contents] + -- Request: .fchar c [contents] + -- Request: .fschar f c [contents] + -- Request: .schar c [contents] + Define a new character or glyph C to be CONTENTS, which can be + empty. More precisely, 'char' defines a 'groff' object (or + redefines an existing one) that is accessed with the name C on + input, and produces CONTENTS on output. Every time glyph C needs + to be printed, CONTENTS is processed in a temporary environment and + the result is wrapped up into a single object. Compatibility mode + is turned off and the escape character is set to '\' while CONTENTS + is processed. Any emboldening, constant spacing, or track kerning + is applied to this object rather than to individual glyphs in + CONTENTS. + + An object defined by these requests can be used just like a normal + glyph provided by the output device. In particular, other + characters can be translated to it with the 'tr' or 'trin' + requests; it can be made the leader character with the 'lc' + request; repeated patterns can be drawn with it using the '\l' and + '\L' escape sequences; and words containing C can be hyphenated + correctly if the 'hcode' request is used to give the object a + hyphenation code. + + There is a special anti-recursion feature: use of the object within + its own definition is handled like a normal character (not defined + with 'char'). + + The 'tr' and 'trin' requests take precedence if 'char' accesses the + same symbol. + + .tr XY + X + => Y + .char X Z + X + => Y + .tr XX + X + => Z + + The 'fchar' request defines a fallback glyph: 'gtroff' only checks + for glyphs defined with 'fchar' if it cannot find the glyph in the + current font. 'gtroff' carries out this test before checking + special fonts. + + 'fschar' defines a fallback glyph for font F: 'gtroff' checks for + glyphs defined with 'fschar' after the list of fonts declared as + font-specific special fonts with the 'fspecial' request, but before + the list of fonts declared as global special fonts with the + 'special' request. + + Finally, the 'schar' request defines a global fallback glyph: + 'gtroff' checks for glyphs defined with 'schar' after the list of + fonts declared as global special fonts with the 'special' request, + but before the already mounted special fonts. + + *Note Character Classes::. + + -- Request: .rchar c ... + -- Request: .rfschar f c ... + Remove definition of each ordinary or special character C, undoing + the effect of a 'char', 'fchar', or 'schar' request. Those + supplied by font description files cannot be removed. Spaces and + tabs may separate C arguments. + + The request 'rfschar' removes glyph definitions defined with + 'fschar' for font F. + + +File: groff.info, Node: Using Symbols-Footnotes, Up: Using Symbols + + (1) Not all versions of the 'man' program support the '-T' option; +use the subsequent example for an alternative. + + (2) This is "Normalization Form D" as documented in Unicode Standard +Annex #15 (<https://unicode.org/reports/tr15/>). + + (3) *Note Compatibility Mode::. + + (4) Output glyphs don't--to GNU 'troff', a glyph is simply a box with +an index into a font, a given height above and depth below the baseline, +and a width. + + +File: groff.info, Node: Character Classes, Next: Special Fonts, Prev: Using Symbols, Up: Using Fonts + +5.19.5 Character Classes +------------------------ + +Classes are particularly useful for East Asian languages such as +Chinese, Japanese, and Korean, where the number of needed characters is +much larger than in European languages, and where large sets of +characters share the same properties. + + -- Request: .class name c1 c2 ... + Define a character class (or simply "class") NAME comprising the + characters C1, C2, and so on. + + A class thus defined can then be referred to in lieu of listing all + the characters within it. Currently, only the 'cflags' request can + handle references to character classes. + + In the request's simplest form, each CN is a character (or special + character). + + .class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq] + + Since class and glyph names share the same name space, it is + recommended to start and end the class name with '[' and ']', + respectively, to avoid collisions with existing character names + defined by GNU 'troff' or the user (with 'char' and related + requests). This practice applies the presence of ']' in the class + name to prevent the use of the special character escape form + '\[...]', thus you must use the '\C' escape to access a class with + such a name. + + You can also use a character range notation consisting of a start + character followed by '-' and then an end character. Internally, + GNU 'troff' converts these two symbol names to Unicode code points + (according to the 'groff' glyph list [GGL]), which then give the + start and end value of the range. If that fails, the class + definition is skipped. + + Furthermore, classes can be nested. + + .class [prepunct] , : ; > } + .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016] + + The class '[prepunctx]' thus contains the contents of the class + '[prepunct]' as defined above (the set ', : ; > }'), and characters + in the range between 'U+2013' and 'U+2016'. + + If you want to include '-' in a class, it must be the first + character value in the argument list, otherwise it gets + misinterpreted as part of the range syntax. + + It is not possible to use class names as end points of range + definitions. + + A typical use of the 'class' request is to control line-breaking + and hyphenation rules as defined by the 'cflags' request. For + example, to inhibit line breaks before the characters belonging to + the 'prepunctx' class defined in the previous example, you can + write the following. + + .cflags 2 \C'[prepunctx]' + + See the 'cflags' request in *note Using Symbols::, for more + details. + + +File: groff.info, Node: Special Fonts, Next: Artificial Fonts, Prev: Character Classes, Up: Using Fonts + +5.19.6 Special Fonts +-------------------- + +Special fonts are those that 'gtroff' searches when it cannot find the +requested glyph in the current font. The Symbol font is usually a +special font. + + 'gtroff' provides the following two requests to add more special +fonts. *Note Using Symbols::, for a detailed description of the glyph +searching mechanism in 'gtroff'. + + Usually, only non-TTY devices have special fonts. + + -- Request: .special [s1 s2 ...] + -- Request: .fspecial f [s1 s2 ...] + Use the 'special' request to define special fonts. Initially, this + list is empty. + + Use the 'fspecial' request to designate special fonts only when + font F is active. Initially, this list is empty. + + Previous calls to 'special' or 'fspecial' are overwritten; without + arguments, the particular list of special fonts is set to empty. + Special fonts are searched in the order they appear as arguments. + + All fonts that appear in a call to 'special' or 'fspecial' are + loaded. + + *Note Using Symbols::, for the exact search order of glyphs. + + +File: groff.info, Node: Artificial Fonts, Next: Ligatures and Kerning, Prev: Special Fonts, Up: Using Fonts + +5.19.7 Artificial Fonts +----------------------- + +There are a number of requests and escape sequences for artificially +creating fonts. These are largely vestiges of the days when output +devices did not have a wide variety of fonts, and when 'nroff' and +'troff' were separate programs. Most of them are no longer necessary in +GNU 'troff'. Nevertheless, they are supported. + + -- Escape sequence: \H'height' + -- Escape sequence: \H'+height' + -- Escape sequence: \H'-height' + -- Register: \n[.height] + Change (increment, decrement) the height of the current font, but + not the width. If HEIGHT is zero, restore the original height. + Default scaling unit is 'z'. + + The read-only register '.height' contains the font height as set by + '\H'. + + Currently, only the '-Tps' and '-Tpdf' devices support this + feature. + + '\H' doesn't produce an input token in GNU 'troff'. As a + consequence, it can be used in requests like 'mc' (which expects a + single character as an argument) to change the font on the fly: + + .mc \H'+5z'x\H'0' + + In compatibility mode, 'gtroff' behaves differently: If an + increment or decrement is used, it is always taken relative to the + current type size and not relative to the previously selected font + height. Thus, + + .cp 1 + \H'+5'test \H'+5'test + + prints the word 'test' twice with the same font height (five points + larger than the current font size). + + -- Escape sequence: \S'slant' + -- Register: \n[.slant] + Slant the current font by SLANT degrees. Positive values slant to + the right. Only integer values are possible. + + The read-only register '.slant' contains the font slant as set by + '\S'. + + Currently, only the '-Tps' and '-Tpdf' devices support this + feature. + + '\S' doesn't produce an input token in GNU 'troff'. As a + consequence, it can be used in requests like 'mc' (which expects a + single character as an argument) to change the font on the fly: + + .mc \S'20'x\S'0' + + This escape is incorrectly documented in the AT&T 'troff' manual; + the slant is always set to an absolute value. + + -- Request: .ul [lines] + The 'ul' request normally underlines subsequent lines if a TTY + output device is used. Otherwise, the lines are printed in italics + (only the term 'underlined' is used in the following). The single + argument is the quantity of input lines to be underlined; with no + argument, the next line is underlined. If LINES is zero or + negative, stop the effects of 'ul' (if it was active). Requests + and empty lines do not count for computing the number of underlined + input lines, even if they produce some output like 'tl'. Lines + inserted by macros (e.g., invoked by a trap) do count. + + At the beginning of 'ul', the current font is stored and the + underline font is activated. Within the span of a 'ul' request, it + is possible to change fonts, but after the last line affected by + 'ul' the saved font is restored. + + This number of lines still to be underlined is associated with the + environment (*note Environments::). The underline font can be + changed with the 'uf' request. + + The 'ul' request does not underline spaces. + + -- Request: .cu [lines] + The 'cu' request is similar to 'ul' but underlines spaces as well + (if a TTY output device is used). + + -- Request: .uf font + Set the underline font (globally) used by 'ul' and 'cu'. By + default, this is the font at position 2. FONT can be either a + non-negative font position or the name of a font. + + -- Request: .bd font [offset] + -- Request: .bd font1 font2 [offset] + -- Register: \n[.b] + Embolden FONT by overstriking its glyphs offset by OFFSET units + minus one. + + Two syntax forms are available. + + * Imitate a bold font unconditionally. The first argument + specifies the font to embolden, and the second is the number + of basic units, minus one, by which the two glyphs are offset. + If the second argument is missing, emboldening is turned off. + + FONT can be either a non-negative font position or the name of + a font. + + OFFSET is available in the '.b' read-only register if a + special font is active; in the 'bd' request, its default unit + is 'u'. + + * Imitate a bold form conditionally. Embolden FONT1 by OFFSET + only if font FONT2 is the current font. This request can be + issued repeatedly to set up different emboldening values for + different current fonts. If the second argument is missing, + emboldening is turned off for this particular current font. + + This affects special fonts only (either set up with the + 'special' command in font files or with the 'fspecial' + request). + + -- Request: .cs font [width [em-size]] + Switch to and from "constant glyph space mode". If activated, the + width of every glyph is WIDTH/36 ems. The em size is given + absolutely by EM-SIZE; if this argument is missing, the em value is + taken from the current font size (as set with the 'ps' request) + when the font is effectively in use. Without second and third + argument, constant glyph space mode is deactivated. + + Default scaling unit for EM-SIZE is 'z'; WIDTH is an integer. + + +File: groff.info, Node: Ligatures and Kerning, Next: Dummy Characters, Prev: Artificial Fonts, Up: Using Fonts + +5.19.8 Ligatures and Kerning +---------------------------- + +Ligatures are groups of characters that are run together, i.e, producing +a single glyph. For example, the letters 'f' and 'i' can form a +ligature 'fi' as in the word 'file'. This produces a cleaner look +(albeit subtle) to the printed output. Usually, ligatures are not +available in fonts for TTY output devices. + + Most PostScript fonts support the fi and fl ligatures. The C/A/T +typesetter that was the target of AT&T 'troff' also supported 'ff', +'ffi', and 'ffl' ligatures. Advanced typesetters or 'expert' fonts may +include ligatures for 'ft' and 'ct', although GNU 'troff' does not +support these (yet). + + Only the current font is checked for ligatures and kerns; neither +special fonts nor special charcters defined with the 'char' request (and +its siblings) are taken into account. + + -- Request: .lg [flag] + -- Register: \n[.lg] + Switch the ligature mechanism on or off; if the parameter is + non-zero or missing, ligatures are enabled, otherwise disabled. + Default is on. The current ligature mode can be found in the + read-only register '.lg' (set to 1 or 2 if ligatures are enabled, + 0 otherwise). + + Setting the ligature mode to 2 enables the two-character ligatures + (fi, fl, and ff) and disables the three-character ligatures (ffi + and ffl). + + "Pairwise kerning" is another subtle typesetting mechanism that +modifies the distance between a glyph pair to improve readability. In +most cases (but not always) the distance is decreased. Typewriter-like +fonts and fonts for terminals where all glyphs have the same width don't +use kerning. + + -- Request: .kern [flag] + -- Register: \n[.kern] + Switch kerning on or off. If the parameter is non-zero or missing, + enable pairwise kerning, otherwise disable it. The read-only + register '.kern' is set to 1 if pairwise kerning is enabled, + 0 otherwise. + + If the font description file contains pairwise kerning information, + glyphs from that font are kerned. Kerning between two glyphs can + be inhibited by placing '\&' between them: 'V\&A'. + + *Note Font Description File Format::. + + "Track kerning" expands or reduces the space between glyphs. This +can be handy, for example, if you need to squeeze a long word onto a +single line or spread some text to fill a narrow column. It must be +used with great care since it is usually considered bad typography if +the reader notices the effect. + + -- Request: .tkf f s1 n1 s2 n2 + Enable track kerning for font F. If the current font is F the + width of every glyph is increased by an amount between N1 and N2 + (N1, N2 can be negative); if the current type size is less than or + equal to S1 the width is increased by N1; if it is greater than or + equal to S2 the width is increased by N2; if the type size is + greater than or equal to S1 and less than or equal to S2 the + increase in width is a linear function of the type size. + + The default scaling unit is 'z' for S1 and S2, 'p' for N1 and N2. + + The track kerning amount is added even to the rightmost glyph in a + line; for large values it is thus recommended to increase the line + length by the same amount to compensate. + + +File: groff.info, Node: Italic Corrections, Next: Dummy Characters, Prev: Ligatures and Kerning, Up: Using Fonts + +5.19.9 Italic Corrections +------------------------- + +When typesetting adjacent glyphs from typefaces of different slants, the +space between them may require adjustment. + + -- Escape sequence: \/ + Apply an "italic correction": modify the spacing of the preceding + glyph so that the distance between it and the following glyph is + correct if the latter is of upright shape. For example, if an + italic 'f' is followed immediately by a roman right parenthesis, + then in many fonts the top right portion of the 'f' overlaps the + top left of the right parenthesis, which is ugly. Use this escape + sequence whenever an oblique glyph is immediately followed by an + upright glyph without any intervening space. + + -- Escape sequence: \, + Apply a "left italic correction": modify the spacing of the + following glyph so that the distance between it and the preceding + glyph is correct if the latter is of upright shape. For example, + if a roman left parenthesis is immediately followed by an + italic 'f', then in many fonts the bottom left portion of the 'f' + overlaps the bottom of the left parenthesis, which is ugly. Use + this escape sequence whenever an upright glyph is followed + immediately by an oblique glyph without any intervening space. + + +File: groff.info, Node: Dummy Characters, Prev: Italic Corrections, Up: Using Fonts + +5.19.10 Dummy Characters +------------------------ + +As discussed in *note Requests and Macros::, the first character on an +input line is treated specially. Further, formatting a glyph has many +consequences on formatter state (*note Environments::). Occasionally, +we want to escape this context or embrace some of those consequences +without actually rendering a glyph to the output. + + -- Escape sequence: \& + Interpolate a dummy character, which is constitutive of output but + invisible.(1) (*note Dummy Characters-Footnote-1::) Its presence + alters the interpretation context of a subsequent input character, + and enjoys several applications. + + * Prevent insertion of extra space after an end-of-sentence + character. + + Test. + Test. + => Test. Test. + Test.\& + Test. + => Test. Test. + + * Prevent recognition of a control character. + + .Test + error-> warning: macro 'Test' not defined + \&.Test + => .Test + + * Prevent kerning between two glyphs. + + * Translate a character to "nothing". + + .tr JIjiK\&k\&UVuv + Post universitum, alea jacta est, OK? + => Post vniversitvm, alea iacta est, O? + + The dummy character escape sequence sees use in macro definitions + as a means of ensuring that arguments are treated as text even if + they begin with spaces or control characters. + + .de HD \" typeset a simple bold heading + . sp + . ft B + \&\\$1 \" exercise: remove the \& + . ft + . sp + .. + .HD .\|.\|.\|surprised? + + One way to think about the dummy character is to imagine placing the +symbol '&' in the input at a certain location; if doing so has all the +side effects on formatting that you desire except for sticking an ugly +ampersand in the midst of your text, the dummy character is what you +want in its place. + + -- Escape sequence: \) + Interpolate a transparent dummy character--one that is transparent + to end-of-sentence detection. It behaves as '\&', except that '\&' + is treated as letters and numerals normally are after '.', '?' and + '!'; '\&' cancels end-of-sentence detection, and '\)' does not. + + .de Suffix-& + . nop \&\\$1 + .. + . + .de Suffix-) + . nop \)\\$1 + .. + . + Here's a sentence.\c + .Suffix-& ' + Another one.\c + .Suffix-) ' + And a third. + => Here's a sentence.' Another one.' And a third. + + +File: groff.info, Node: Dummy Characters-Footnotes, Up: Dummy Characters + + (1) Opinions of this escape sequence's name abound. "Zero-width +space" is a popular misnomer: 'roff' formatters do not treat it like a +space. Ossanna called it a "non-printing, zero-width character", but +the character causes _output_ even though it does not "print". If no +output line is pending, the dummy character starts one. Contrast an +empty input document with one containing only '\&'. The former produces +no output; the latter, a blank page. + + +File: groff.info, Node: Manipulating Type Size and Vertical Spacing, Next: Colors, Prev: Using Fonts, Up: GNU troff Reference + +5.20 Manipulating Type Size and Vertical Spacing +================================================ + +These concepts were introduced in *note Page Geometry::. The height of +a font's tallest glyph is one em, which is equal to the type size in +points.(1) (*note Manipulating Type Size and Vertical +Spacing-Footnote-1::) A vertical spacing of less than 120% of the type +size can make a document hard to read. Larger proportions can be useful +to spread the text for annotations or proofreader's marks. By default, +GNU 'troff' uses 10 point type on 12 point spacing. Typographers call +the difference between type size and vertical spacing "leading".(2) +(*note Manipulating Type Size and Vertical Spacing-Footnote-2::) + +* Menu: + +* Changing the Type Size:: +* Changing the Vertical Spacing:: +* Using Fractional Type Sizes:: + + +File: groff.info, Node: Manipulating Type Size and Vertical Spacing-Footnotes, Up: Manipulating Type Size and Vertical Spacing + + (1) In text fonts, the tallest glyphs are typically parentheses. +Unfortunately, in many cases the actual dimensions of the glyphs in a +font do not closely match its declared type size! For example, in the +standard PostScript font families, 10-point Times sets better with +9-point Helvetica and 11-point Courier than if all three were used at +10 points. + + (2) Rhyme with "sledding"; mechanical typography used lead metal +(Latin _plumbum_). + + +File: groff.info, Node: Changing the Type Size, Next: Changing the Vertical Spacing, Prev: Manipulating Type Size and Vertical Spacing, Up: Manipulating Type Size and Vertical Spacing + +5.20.1 Changing the Type Size +----------------------------- + + -- Request: .ps [size] + -- Request: .ps +size + -- Request: .ps -size + -- Escape sequence: \ssize + -- Register: \n[.s] + Use the 'ps' request or the '\s' escape sequence to change + (increase, decrease) the type size (in scaled points). Specify + SIZE as either an absolute type size, or as a relative change from + the current size. 'ps' with no argument restores the previous + size. The 'ps' request's default scaling unit is 'z'. The + requested size is rounded to the nearest valid size (with ties + rounding down) within the limits supported by the device. If the + requested size is non-positive, it is treated as 1u. + + Type size alteration is incorrectly documented in the AT&T 'troff' + manual, which claims "if [the requested size] is invalid, the next + larger valid size will result, with a maximum of 36".(1) (*note + Changing the Type Size-Footnote-1::) + + The read-only string-valued register '.s' interpolates the type + size in points as a decimal fraction; it is associated with the + environment (*note Environments::). To obtain the type size in + scaled points, interpolate the '.ps' register instead (*note Using + Fractional Type Sizes::). + + The '\s' escape sequence supports a variety of syntax forms. + + '\sN' + Set the type size to N points. N must be a single digit. If + N is 0, restore the previous size. + + '\s+N' + '\s-N' + Increase or decrease the type size by N points. N must be + exactly one digit. + + '\s(NN' + Set the type size to NN points. NN must be exactly two + digits. + + '\s+(NN' + '\s-(NN' + '\s(+NN' + '\s(-NN' + Alter the type size in points by the two-digit value NN. + + *Note Using Fractional Type Sizes::, for further syntactical forms + of the '\s' escape sequence that additionally accept decimal + fractions. + + snap, snap, + .ps +2 + grin, grin, + .ps +2 + wink, wink, \s+2nudge, nudge,\s+8 say no more! + .ps 10 + + The '\s' escape sequence affects the environment immediately and +doesn't produce an input token. Consequently, it can be used in +requests like 'mc', which expects a single character as an argument, to +change the type size on the fly. + + .mc \s[20]x\s[0] + + -- Request: .sizes s1 s2 ... sn [0] + The 'DESC' file specifies which type sizes are allowed by the + output device; see *note DESC File Format::. Use the 'sizes' + request to change this set of permissible sizes. Arguments are in + scaled points; see *note Using Fractional Type Sizes::. Each can + be a single type size (such as '12000'), or a range of sizes (such + as '4000-72000'). You can optionally end the list with a '0'. + + +File: groff.info, Node: Changing the Type Size-Footnotes, Up: Changing the Type Size + + (1) The claim appears to have been true of Ossanna 'troff' for the +C/A/T device; Kernighan made device-independent 'troff' more flexible. + + +File: groff.info, Node: Changing the Vertical Spacing, Next: Using Fractional Type Sizes, Prev: Changing the Type Size, Up: Manipulating Type Size and Vertical Spacing + +5.20.2 Changing the Vertical Spacing +------------------------------------ + + -- Request: .vs [space] + -- Request: .vs +space + -- Request: .vs -space + -- Register: \n[.v] + Set the vertical spacing to, or alter it by, SPACE. The default + scaling unit is 'p'. If 'vs' is called without an argument, the + vertical spacing is reset to the previous value before the last + call to 'vs'. GNU 'troff' emits a warning in category 'range' if + SPACE is negative; the vertical spacing is then set to the smallest + possible positive value, the vertical motion quantum (as found in + the '.V' register). + + '.vs 0' isn't saved in a diversion since it doesn't result in a + vertical motion. You must explicitly issue this request before + interpolating the diversion. + + The read-only register '.v' contains the vertical spacing; it is + associated with the environment (*note Environments::). + +When a break occurs, GNU 'troff' performs the following procedure. + + * Move the drawing position vertically by the "extra pre-vertical + line space", the minimum of all negative '\x' escape sequence + arguments in the pending output line. + + * Move the drawing position vertically by the vertical line spacing. + + * Write out the pending output line. + + * Move the drawing position vertically by the "extra post-vertical + line space", the maximum of all positive '\x' escape sequence + arguments in the line that has just been output. + + * Move the drawing position vertically by the "post-vertical line + spacing" (see below). + + Prefer 'vs' or 'pvs' over 'ls' to produce double-spaced documents. +'vs' and 'pvs' have finer granularity than 'ls'; moreover, some +preprocessors assume single spacing. *Note Manipulating Spacing::, +regarding the '\x' escape sequence and the 'ls' request. + + -- Request: .pvs [space] + -- Request: .pvs +space + -- Request: .pvs -space + -- Register: \n[.pvs] + Set the post-vertical spacing to, or alter it by, SPACE. The + default scaling unit is 'p'. If 'pvs' is called without an + argument, the post-vertical spacing is reset to the previous value + before the last call to 'pvs'. GNU 'troff' emits a warning in + category 'range' if SPACE is negative; the post-vertical spacing is + then set to zero. + + The read-only register '.pvs' contains the post-vertical spacing; + it is associated with the environment (*note Environments::). + + +File: groff.info, Node: Using Fractional Type Sizes, Prev: Changing the Type Size, Up: Manipulating Type Size and Vertical Spacing + +5.20.3 Using Fractional Type Sizes +---------------------------------- + +AT&T 'troff' interpreted all type size measurements in points. Combined +with integer arithmetic, this design choice made it impossible to +support, for instance, ten and a half-point type. In GNU 'troff', an +output device can select a scaling factor that subdivides a point into +"scaled points". A type size expressed in scaled points can thus +represent a non-integral type size. + + A "scaled point" is equal to 1/SIZESCALE points, where SIZESCALE is +specified in the device description file 'DESC', and defaults to 1.(1) +(*note Using Fractional Type Sizes-Footnote-1::) Requests and escape +sequences in GNU 'troff' interpret arguments that represent a type size +in scaled points, which the formatter multiplies by SIZESCALE and +converts to an integer. Arguments treated in this way comprise those to +the escape sequences '\H' and '\s', to the request 'ps', the third +argument to the 'cs' request, and the second and fourth arguments to the +'tkf' request. Scaled points may be specified explicitly with the 'z' +scaling unit. + + For example, if SIZESCALE is 1000, then a scaled point is one +thousandth of a point. The request '.ps 10.5' is synonymous with '.ps +10.5z' and sets the type size to 10,500 scaled points, or 10.5 points. +Consequently, in GNU 'troff', the register '.s' can interpolate a +non-integral type size. + + -- Register: \n[.ps] + This read-only register interpolates the type size in scaled + points; it is associated with the environment (*note + Environments::). + + It makes no sense to use the 'z' scaling unit in a numeric expression +whose default scaling unit is neither 'u' nor 'z', so GNU 'troff' +disallows this. Similarly, it is nonsensical to use a scaling unit +other than 'z' or 'u' in a numeric expression whose default scaling unit +is 'z', and so GNU 'troff' disallows this as well. + + Another GNU 'troff' scaling unit, 's', multiplies by the number of +basic units in a scaled point. Thus, '\n[.ps]s' is equal to '1m' by +definition. Do not confuse the 's' and 'z' scaling units. + + -- Register: \n[.psr] + -- Register: \n[.sr] + Output devices may be limited in the type sizes they can employ. + The '.s' and '.ps' registers represent the type size selected by + the output driver as it understands a device's capability. The + last _requested_ type size is interpolated in scaled points by the + read-only register '.psr' and in points as a decimal fraction by + the read-only string-valued register '.sr'. Both are associated + with the environment (*note Environments::). + + For example, if a type size of 10.95 points is requested, and the + nearest size permitted by a 'sizes' request (or by the 'sizes' or + 'sizescale' directives in the device's 'DESC' file) is 11 points, + the output driver uses the latter value. + + The '\s' escape sequence offers the following syntax forms that work +with fractional type sizes and accept scaling units. You may of course +give them integral arguments. The delimited forms need not use the +neutral apostrophe; see *note Delimiters::. + +'\s[N]' +'\s'N'' + Set the type size to N scaled points; N is a numeric expression + with a default scaling unit of 'z'. + +'\s[+N]' +'\s[-N]' +'\s+[N]' +'\s-[N]' +'\s'+N'' +'\s'-N'' +'\s+'N'' +'\s-'N'' + Increase or decrease the type size by N scaled points; N is a + numeric expression (which may start with a minus sign) with a + default scaling unit of 'z'. + + +File: groff.info, Node: Using Fractional Type Sizes-Footnotes, Up: Using Fractional Type Sizes + + (1) *Note Device and Font Description Files::. + + +File: groff.info, Node: Colors, Next: Strings, Prev: Manipulating Type Size and Vertical Spacing, Up: GNU troff Reference + +5.21 Colors +=========== + +GNU 'troff' supports color output with a variety of color spaces and up +to 16 bits per channel. Some devices, particularly terminals, may be +more limited. When color support is enabled, two colors are current at +any given time: the "stroke color", with which glyphs, rules (lines), +and geometric objects like circles and polygons are drawn, and the "fill +color", which can be used to paint the interior of a closed geometric +figure. + + -- Request: .color [n] + -- Register: \n[.color] + If N is missing or non-zero, enable the output of color-related + device-independent output commands (this is the default); + otherwise, disable them. This request sets a global flag; it does + not produce an input token (*note Gtroff Internals::). + + The read-only register '.color' is 1 if colors are enabled, + 0 otherwise. + + Color can also be disabled with the '-c' command-line option. + + -- Request: .defcolor ident scheme color-component ... + Define a color named IDENT. SCHEME selects a color space and + determines the quantity of required COLOR-COMPONENTs; it must be + one of 'rgb' (three components), 'cmy' (three), 'cmyk' (four), or + 'gray' (one). 'grey' is accepted as a synonym of 'gray'. The + color components can be encoded as a single hexadecimal value + starting with '#' or '##'. The former indicates that each + component is in the range 0-255 (0-FF), the latter the range + 0-65,535 (0-FFFF). + + .defcolor half gray #7f + .defcolor pink rgb #FFC0CB + .defcolor magenta rgb ##ffff0000ffff + + Alternatively, each color component can be specified as a decimal + fraction in the range 0-1, interpreted using a default scaling unit + of 'f', which multiplies its value by 65,536 (but clamps it at + 65,535). + + .defcolor gray50 rgb 0.5 0.5 0.5 + .defcolor darkgreen rgb 0.1f 0.5f 0.2f + + Each output device has a color named 'default', which cannot be +redefined. A device's default stroke and fill colors are not +necessarily the same. For the 'dvi', 'html', 'pdf', 'ps', and 'xhtml' +output devices, GNU 'troff' automatically loads a macro file defining +many color names at startup. By the same mechanism, the devices +supported by 'grotty' recognize the eight standard ISO 6429/EMCA-48 +color names.(1) (*note Colors-Footnote-1::) + + -- Request: .gcolor [color] + -- Escape sequence: \mc + -- Escape sequence: \m(co + -- Escape sequence: \m[color] + -- Register: \n[.m] + Set the stroke color to COLOR. + + .gcolor red + The next words + .gcolor + \m[red]are in red\m[] + and these words are in the previous color. + + The escape sequence '\m[]' restores the previous stroke color, as + does a 'gcolor' request without an argument. + + The name of the current stroke color is available in the read-only + string-valued register '.m'; it is associated with the environment + (*note Environments::). It interpolates nothing when the stroke + color is the default. + + '\m' doesn't produce an input token in GNU 'troff' (*note Gtroff + Internals::). It therefore 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[] + + -- Request: .fcolor [color] + -- Escape sequence: \Mc + -- Escape sequence: \M(co + -- Escape sequence: \M[color] + -- Register: \n[.M] + Set the fill color for objects drawn with '\D'...'' escape + sequences. The escape sequence '\M[]' restores the previous fill + color, as does an 'fcolor' request without an argument. + + The name of the current fill color is available in the read-only + string-valued register '.M'; it is associated with the environment + (*note Environments::). It interpolates nothing when the fill + color is the default. '\M' doesn't produce an input token in GNU + 'troff'. + + Create an ellipse with a red interior as follows. + + \M[red]\h'0.5i'\D'E 2i 1i'\M[] + + +File: groff.info, Node: Colors-Footnotes, Up: Colors + + (1) also known vulgarly as "ANSI colors" + + +File: groff.info, Node: Strings, Next: Conditionals and Loops, Prev: Colors, Up: GNU troff Reference + +5.22 Strings +============ + +GNU 'troff' supports strings primarily for user convenience. +Conventionally, if one would define a macro only to interpolate a small +amount of text, without invoking requests or calling any other macros, +one defines a string instead. Only one string is predefined by the +language. + + -- String: \*[.T] + Contains the name of the output device (for example, 'utf8' or + 'pdf'). + + The 'ds' request creates a string with a specified name and contents +and the '\*' escape sequence dereferences its name, interpolating its +contents. If the string named by the '\*' escape sequence does not +exist, it is defined as empty, nothing is interpolated, and a warning in +category 'mac' is emitted. *Note Warnings::, for information about the +enablement and suppression of warnings. + + -- Request: .ds name [contents] + -- Request: .ds1 name [contents] + -- Escape sequence: \*n + -- Escape sequence: \*(nm + -- Escape sequence: \*[name [arg1 arg2 ...]] + Define a string called NAME with contents CONTENTS. If NAME + already exists as an alias, the target of the alias is redefined; + see 'als' and 'rm' below. If 'ds' is called with only one + argument, NAME is defined as an empty string. Otherwise, GNU + 'troff' stores CONTENTS in copy mode.(1) (*note + Strings-Footnote-1::) + + The '\*' escape sequence interpolates a previously defined string + variable NAME (one-character name N, two-character name NM). The + bracketed interpolation form accepts arguments that are handled as + macro arguments are; recall *note Calling Macros::. In contrast to + macro calls, however, if a closing bracket ']' occurs in a string + argument, that argument must be enclosed in double quotes. '\*' is + interpreted even in copy mode. When defining strings, argument + interpolations must be escaped if they are to reference parameters + from the calling context; *Note Parameters::. + + .ds cite (\\$1, \\$2) + Gray codes are explored in \*[cite Morgan 1998]. + => Gray codes are explored in (Morgan, 1998). + + *Caution:* Unlike other requests, the second argument to the 'ds' + request consumes the remainder of the input line, including + trailing spaces. This means that comments on a line with such a + request can introduce unwanted space into a string when they are + set off from the material they annotate, as is conventional. + + .ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water + + Instead, place the comment on another line or put the comment + escape sequence immediately adjacent to the last character of the + string. + + .ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O\" water + + Ending string definitions (and appendments) with a comment, even an + empty one, prevents unwanted space from creeping into them during + source document maintenance. + + .ds author Alice Pleasance Liddell\" + .ds empty \" might be appended to later with .as + + An initial neutral double quote '"' in CONTENTS is stripped to + allow embedding of leading spaces. Any other '"' is interpreted + literally, but it is wise to use the special character escape + sequence '\[dq]' instead if the string might be interpolated as + part of a macro argument; see *note Calling Macros::. + + .ds salutation " Yours in a white wine sauce,\" + .ds c-var-defn " char mydate[]=\[dq]2020-07-29\[dq];\" + + Strings are not limited to a single input line of text. '\<RET>' + works just as it does elsewhere. The resulting string is stored + _without_ the newlines. Care is therefore required when + interpolating strings while filling is disabled. + + .ds foo This string contains \ + text on multiple lines \ + of input. + + It is not possible to embed a newline in a string that will be + interpreted as such when the string is interpolated. To achieve + that effect, use '\*' to interpolate a macro instead; see *note + Punning Names::. + + Because strings are similar to macros, they too can be defined so + as to suppress AT&T 'troff' compatibility mode when used; see *note + Writing Macros:: and *note Compatibility Mode::. The 'ds1' request + defines a string such that compatibility mode is off when the + string is later interpolated. To be more precise, a "compatibility + save" input token is inserted at the beginning of the string, and a + "compatibility restore" input token at the end. + + .nr xxx 12345 + .ds aa The value of xxx is \\n[xxx]. + .ds1 bb The value of xxx is \\n[xxx]. + . + .cp 1 + . + \*(aa + error-> warning: register '[' not defined + => The value of xxx is 0xxx]. + \*(bb + => The value of xxx is 12345. + + -- Request: .as name [contents] + -- Request: .as1 name [contents] + The 'as' request is similar to 'ds' but appends CONTENTS to the + string stored as NAME instead of redefining it. If NAME doesn't + exist yet, it is created. If 'as' is called with only one + argument, no operation is performed (beyond dereferencing the + string). + + .as salutation " with shallots, onions and garlic,\" + + The 'as1' request is similar to 'as', but compatibility mode is + switched off when the appended portion of the string is later + interpolated. To be more precise, a "compatibility save" input + token is inserted at the beginning of the appended string, and a + "compatibility restore" input token at the end. + + Several requests exist to perform rudimentary string operations. +Strings can be queried ('length') and modified ('chop', 'substring', +'stringup', 'stringdown'), and their names can be manipulated through +renaming, removal, and aliasing ('rn', 'rm', 'als'). + + -- Request: .length reg anything + Compute the number of characters of ANYTHING and store the count in + the register REG. If REG doesn't exist, it is created. ANYTHING + is read in copy mode. + + .ds xxx abcd\h'3i'efgh + .length yyy \*[xxx] + \n[yyy] + => 14 + + -- Request: .chop object + Remove the last character from the macro, string, or diversion + named OBJECT. This is useful for removing the newline from the end + of a diversion that is to be interpolated as a string. This + request can be used repeatedly on the same OBJECT; see *note Gtroff + Internals::, for details on nodes inserted additionally by GNU + 'troff'. + + -- Request: .substring str start [end] + Replace the string named STR with its substring bounded by the + indices START and END, inclusively. The first character in the + string has index 0. If END is omitted, it is implicitly set to the + largest valid value (the string length minus one). Negative + indices count backward from the end of the string: the last + character has index -1, the character before the last has index -2, + and so on. + + .ds xxx abcdefgh + .substring xxx 1 -4 + \*[xxx] + => bcde + .substring xxx 2 + \*[xxx] + => de + + -- Request: .stringdown str + -- Request: .stringup str + Alter the string named STR by replacing each of its bytes with its + lowercase ('stringdown') or uppercase ('stringup') version (if one + exists). Special characters in the string will often transform in + the expected way due to the regular naming convention for accented + characters. When they do not, use substrings and/or catenation. + + .ds resume R\['e]sum\['e] + \*[resume] + .stringdown resume + \*[resume] + .stringup resume + \*[resume] + => Résumé résumé RÉSUMÉ + + (In practice, we would end the 'ds' request with a comment escape +'\"' to prevent space from creeping into the definition during source +document maintenance.) + + -- Request: .rn old new + Rename the request, macro, diversion, or string OLD to NEW. + + -- Request: .rm name + Remove the request, macro, diversion, or string NAME. GNU 'troff' + treats subsequent invocations as if the name had never been + defined. + + -- Request: .als new old + Create an alias NEW for the existing request, string, macro, or + diversion object named OLD, causing the names to refer to the same + stored object. If OLD is undefined, a warning in category 'mac' is + produced, and the request is ignored. *Note Warnings::, for + information about the enablement and suppression of warnings. + + To understand how the 'als' request works, consider two different + storage pools: one for objects (macros, strings, etc.), and another + for names. As soon as an object is defined, GNU 'troff' adds it to + the object pool, adds its name to the name pool, and creates a link + between them. When 'als' creates an alias, it adds a new name to + the name pool that gets linked to the same object as the old name. + + Now consider this example. + + .de foo + .. + . + .als bar foo + . + .de bar + . foo + .. + . + .bar + error-> input stack limit exceeded (probable infinite + error-> loop) + + In the above, 'bar' remains an _alias_--another name for--the + object referred to by 'foo', which the second 'de' request + replaces. Alternatively, imagine that the 'de' request + _dereferences_ its argument before replacing it. Either way, the + result of calling 'bar' is a recursive loop that finally leads to + an error. *Note Writing Macros::. + + To remove an alias, call 'rm' on its name. The object itself is + not destroyed until it has no more names. + + When a request, macro, string, or diversion is aliased, + redefinitions and appendments "write through" alias names. To + replace an alias with a separately defined object, you must use the + 'rm' request on its name first. + + +File: groff.info, Node: Strings-Footnotes, Up: Strings + + (1) *Note Copy Mode::. + + +File: groff.info, Node: Conditionals and Loops, Next: Writing Macros, Prev: Strings, Up: GNU troff Reference + +5.23 Conditionals and Loops +=========================== + +'groff' has 'if' and 'while' control structures like other languages. +However, the syntax for grouping multiple input lines in the branches or +bodies of these structures is unusual. + +* Menu: + +* Operators in Conditionals:: +* if-then:: +* if-else:: +* Conditional Blocks:: +* while:: + + +File: groff.info, Node: Operators in Conditionals, Next: if-then, Prev: Conditionals and Loops, Up: Conditionals and Loops + +5.23.1 Operators in Conditionals +-------------------------------- + +In 'if', 'ie', and 'while' requests, in addition to the numeric +expressions described in *note Numeric Expressions::, several Boolean +operators are available; the members of this expanded class are termed +"conditional expressions". + +'c GLYPH' + True if GLYPH is available, where GLYPH is an ordinary character, a + special character '\(XX' or '\[XXX]', '\N'XXX'', or has been + defined by any of the 'char', 'fchar', 'fschar', or 'schar' + requests. + +'d NAME' + True if a string, macro, diversion, or request called NAME exists. + +'e' + True if the current page is even-numbered. + +'F FONT' + True if FONT exists. FONT is handled as if it were opened with the + 'ft' request (that is, font translation and styles are applied), + without actually mounting it. + +'m COLOR' + True if COLOR is defined. + +'n' + True if the document is being processed in 'nroff' mode. *Note + troff and nroff Modes::. + +'o' + True if the current page is odd-numbered. + +'r REGISTER' + True if REGISTER exists. + +'S STYLE' + True if STYLE is available for the current font family. Font + translation is applied. + +'t' + True if the document is being processed in 'troff' mode. *Note + troff and nroff Modes::. + +'v' + Always false. This condition is recognized only for compatibility + with certain other 'troff' implementations.(1) (*note Operators in + Conditionals-Footnote-1::) + + If the first argument to an 'if', 'ie', or 'while' request begins +with a non-alphanumeric character apart from '!' (see below); it +performs an output comparison test. (2) (*note Operators in +Conditionals-Footnote-2::) + +''XXX'YYY'' + True if formatting the comparands XXX and YYY produces the same + output commands. The delimiter need not be a neutral apostrophe: + the output comparison operator accepts the same delimiters as most + escape sequences; see *note Delimiters::. This "output comparison + operator" formats XXX and YYY in separate environments; after the + comparison, the resulting data are discarded. + + .ie "|"\fR|\fP" true + .el false + => true + + The resulting glyph properties, including font family, style, size, + and slant, must match, but not necessarily the requests and/or + escape sequences used to obtain them. In the previous example, '|' + and '\fR|\fP' result in '|' glyphs in the same typefaces at the + same positions, so the comparands are equal. If '.ft I' had been + added before the '.ie', they would differ: the first '|' would + produce an italic '|', not a roman one. Motions must match in + orientation and magnitude to within the applicable horizontal and + vertical motion quanta of the device, after rounding. '.if + "\u\d"\v'0'"' is false even though both comparands result in zero + net motion, because motions are not interpreted or optimized but + sent as-is to the output.(3) (*note Operators in + Conditionals-Footnote-3::) On the other hand, '.if "\d"\v'0.5m'"' + is true, because '\d' is defined as a downward motion of one-half + em.(4) (*note Operators in Conditionals-Footnote-4::) + + Surround the comparands with '\?' to avoid formatting them; this + causes them to be compared character by character, as with string + comparisons in other programming languages. + + .ie "\?|\?"\?\fR|\fP\?" true + .el false + => false + + Since comparands protected with '\?' are read in copy mode (*note + Copy Mode::), they need not even be valid 'groff' syntax. The + escape character is still lexically recognized, however, and + consumes the next character. + + .ds a \[ + .ds b \[ + .if '\?\*a\?'\?\*b\?' a and b equivalent + .if '\?\\?'\?\\?' backslashes equivalent + => a and b equivalent + + The above operators can't be combined with most others, but a leading +'!', not followed immediately by spaces or tabs, complements an +expression. + + .nr x 1 + .ie !r x register x is not defined + .el register x is defined + => register x is defined + + Spaces and tabs are optional immediately after the 'c', 'd', 'F', +'m', 'r', and 'S' operators, but right after '!', they end the predicate +and the conditional evaluates true.(5) (*note Operators in +Conditionals-Footnote-5::) + + .nr x 1 + .ie ! r x register x is not defined + .el register x is defined + => r x register x is not defined + +The unexpected 'r x' in the output is a clue that our conditional was +not interpreted as we planned, but matters may not always be so obvious. + + +File: groff.info, Node: Operators in Conditionals-Footnotes, Up: Operators in Conditionals + + (1) This refers to 'vtroff', a translator that would convert the +C/A/T output from early-vintage AT&T 'troff' to a form suitable for +Versatec and Benson-Varian plotters. + + (2) Strictly, letters not otherwise recognized _are_ treated as +output comparison delimiters. For portability, it is wise to avoid +using letters not in the list above; for example, Plan 9 'troff' uses +'h' to test a mode it calls 'htmlroff', and GNU 'troff' may provide +additional operators in the future. + + (3) Because formatting of the comparands takes place in a dummy +environment, vertical motions within them cannot spring traps. + + (4) All of this is to say that the lists of output nodes created by +formatting XXX and YYY must be identical. *Note Gtroff Internals::. + + (5) This bizarre behavior maintains compatibility with AT&T 'troff'. + + +File: groff.info, Node: if-then, Next: if-else, Prev: Operators in Conditionals, Up: Conditionals and Loops + +5.23.2 if-then +-------------- + + -- Request: .if cond-expr anything + Evaluate the conditional expression COND-EXPR, and if it evaluates + true (or to a positive value), interpret the remainder of the line + ANYTHING as if it were an input line. Recall from *note Invoking + Requests:: that any quantity of spaces between arguments to + requests serves only to separate them; leading spaces in ANYTHING + are thus not seen. ANYTHING effectively _cannot_ be omitted; if + COND-EXPR is true and ANYTHING is empty, the newline at the end of + the control line is interpreted as a blank input line (and + therefore a blank text line). + + super\c + tanker + .nr force-word-break 1 + super\c + .if ((\n[force-word-break] = 1) & \n[.int]) + tanker + => supertanker super tanker + + -- Request: .nop anything + Interpret ANYTHING as if it were an input line. This is similar to + '.if 1'. 'nop' is not really "no operation"; its argument _is_ + processed--unconditionally. It can be used to cause text lines to + share indentation with surrounding control lines. + + .als real-MAC MAC + .de wrapped-MAC + . tm MAC: called with arguments \\$@ + . nop \\*[real-MAC]\\ + .. + .als MAC wrapped-MAC + \# Later... + .als MAC real-MAC + + In the above, we've used aliasing, 'nop', and the interpolation of + a macro as a string to interpose a wrapper around the macro 'MAC' + (perhaps to debug it). + + +File: groff.info, Node: if-else, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops + +5.23.3 if-else +-------------- + + -- Request: .ie cond-expr anything + -- Request: .el anything + Use the 'ie' and 'el' requests to write an if-then-else. The first + request is the "if" part and the latter is the "else" part. + Unusually among programming languages, any number of + non-conditional requests may be interposed between the 'ie' branch + and the 'el' branch. + + .nr a 0 + .ie \na a is non-zero. + .nr a +1 + .el a was not positive but is now \na. + => a was not positive but is now 1. + + Another way in which 'el' is an ordinary request is that it does + not lexically "bind" more tightly to its 'ie' counterpart than it + does to any other request. This fact can surprise C programmers. + + .nr a 1 + .nr z 0 + .ie \nz \ + . ie \na a is true + . el a is false + .el z is false + error-> warning: unbalanced 'el' request + => a is false + + To conveniently nest conditionals, keep reading. + + +File: groff.info, Node: Conditional Blocks, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops + +5.23.4 Conditional Blocks +------------------------- + +It is frequently desirable for a control structure to govern more than +one request, macro call, text line, or a combination of the foregoing. +The opening and closing brace escape sequences '\{' and '\}' define such +groups. These "conditional blocks" can furthermore be nested. + + -- Escape sequence: \{ + -- Escape sequence: \} + '\{' begins a conditional block; it must appear (after optional + spaces and tabs) immediately subsequent to the conditional + expression of an 'if', 'ie', or 'while' request,(1) (*note + Conditional Blocks-Footnote-1::) or as the argument to an 'el' + request. + + '\}' ends a condition block and should appear on a line with other + occurrences of itself as necessary to match '\{' sequences. It can + be preceded by a control character, spaces, and tabs. Input after + any quantity of '\}' sequences on the same line is processed only + if all of the preceding conditions to which they correspond are + true. Furthermore, a '\}' closing the body of a 'while' request + must be the last such escape sequence on an input line. + + Brace escape sequences outside of control structures have no + meaning and produce no output. + + *Caution:* Input lines using '\{' often end with '\RET', especially + in macros that consist primarily of control lines. Forgetting to + use '\RET' on an input line after '\{' is a common source of error. + + We might write the following in a page header macro. If we delete +'\RET', the header will carry an unwanted extra empty line (except on +page 1). + + .if (\\n[%] != 1) \{\ + . ie ((\\n[%] % 2) = 0) .tl \\*[even-numbered-page-title] + . el .tl \\*[odd-numbered-page-title] + .\} + + Let us take a closer look at how conditional blocks nest. + + A + .if 0 \{ B + C + D + \}E + F + => A F + + N + .if 1 \{ O + . if 0 \{ P + Q + R\} S\} T + U + => N O U + + The above behavior may challenge the intuition; it was implemented to +retain compatibility with AT&T 'troff'. For clarity, it is idiomatic to +end input lines with '\{' (followed by '\<RET>' if appropriate), and to +precede '\}' on an input line with nothing more than a control +character, spaces, tabs, and other instances of itself. + + We can use 'ie', 'el', and conditional blocks to simulate the +multi-way "switch" or "case" control structures of other languages. The +following example is adapted from the 'groff' 'man' package. +Indentation is used to clarify the logic. + + .\" Simulate switch/case in roff. + . ie '\\$2'1' .ds title General Commands\" + .el \{.ie '\\$2'2' .ds title System Calls\" + .el \{.ie '\\$2'3' .ds title Library Functions\" + .el \{.ie '\\$2'4' .ds title Kernel Interfaces\" + .el \{.ie '\\$2'5' .ds title File Formats\" + .el \{.ie '\\$2'6' .ds title Games\" + .el \{.ie '\\$2'7' .ds title Miscellaneous Information\" + .el \{.ie '\\$2'8' .ds title System Management\" + .el \{.ie '\\$2'9' .ds title Kernel Development\" + .el .ds title \" empty + .\}\}\}\}\}\}\}\} + + +File: groff.info, Node: Conditional Blocks-Footnotes, Up: Conditional Blocks + + (1) *Note while::. + + +File: groff.info, Node: while, Prev: if-else, Up: Conditionals and Loops + +5.23.5 while +------------ + +'groff' provides a looping construct: the 'while' request. Its syntax +matches the 'if' request. + + -- Request: .while cond-expr anything + Evaluate the conditional expression COND-EXPR, and repeatedly + execute ANYTHING unless and until COND-EXPR evaluates false. + ANYTHING, which is often a conditional block, is referred to as the + 'while' request's "body". + + .nr a 0 1 + .while (\na < 9) \{\ + \n+a, + .\} + \n+a + => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 + + GNU 'troff' treats the body of a 'while' request similarly to that + of a 'de' request (albeit one not read in copy mode(1) (*note + while-Footnote-1::)), but stores it under an internal name and + deletes it when the loop finishes. The operation of a macro + containing a 'while' request can slow significantly if the 'while' + body is large. Each time the macro is executed, the 'while' body + is parsed and stored again. + + .de xxx + . nr num 10 + . while (\\n[num] > 0) \{\ + . \" many lines of code + . nr num -1 + . \} + .. + + An often better solution--and one that is more portable, since AT&T + 'troff' lacked the 'while' request--is to instead write a recursive + macro. It will be parsed only once.(2) (*note while-Footnote-2::) + + .de yyy + . if (\\n[num] > 0) \{\ + . \" many lines of code + . nr num -1 + . yyy + . \} + .. + . + .de xxx + . nr num 10 + . yyy + .. + + To prevent infinite loops, the default number of available + recursion levels is 1,000 or somewhat less.(3) (*note + while-Footnote-3::) You can disable this protective measure, or + raise the limit, by setting the 'slimit' register. *Note + Debugging::. + + As noted above, if a 'while' body begins with a conditional block, + its closing brace must end an input line. + + .if 1 \{\ + . nr a 0 1 + . while (\n[a] < 10) \{\ + . nop \n+[a] + .\}\} + error-> unbalanced brace escape sequences + + -- Request: .break + Exit a 'while' loop. Do not confuse this request with a + typographical break or the 'br' request. + + -- Request: .continue + Skip the remainder of a 'while' loop's body, immediately starting + the next iteration. + + +File: groff.info, Node: while-Footnotes, Up: while + + (1) *Note Copy Mode::. + + (2) unless you redefine it + + (3) "somewhat less" because things other than macro calls can be on +the input stack + + +File: groff.info, Node: Writing Macros, Next: Page Motions, Prev: Conditionals and Loops, Up: GNU troff Reference + +5.24 Writing Macros +=================== + +A "macro" is a stored collection of text and control lines that can be +interpolated multiple times. Use macros to define common operations. +Macros are called in the same way that requests are invoked. While +requests exist for the purpose of creating macros, simply calling an +undefined macro, or interpolating it as a string, will cause it to be +defined as empty. *Note Identifiers::. + + -- Request: .de name [end] + Define a macro NAME, replacing the definition of any existing + request, macro, string, or diversion called NAME. If NAME already + exists as an alias, the target of the alias is redefined; recall + *note Strings::. GNU 'troff' enters copy mode,(1) (*note Writing + Macros-Footnote-1::) storing subsequent input lines as the macro + definition. If the optional second argument is not specified, the + definition ends with the control line '..' (two dots). + Alternatively, END identifies a macro whose call syntax at the + start of a control line ends the definition of NAME; END is then + called normally. A macro definition must end in the same + conditional block (if any) in which it began (*note Conditional + Blocks::). Spaces or tabs are permitted after the control + character in the line containing this ending token (either '.' or + 'END'), but a tab immediately after the token prevents its + recognition as the end of a macro definition. The macro END can be + called with arguments.(2) (*note Writing Macros-Footnote-2::) + + Here is a small example macro called 'P' that causes a break and + inserts some vertical space. It could be used to separate + paragraphs. + + .de P + . br + . sp .8v + .. + + We can define one macro within another. Attempting to nest '..' + naïvely will end the outer definition because the inner definition + isn't interpreted as such until the outer macro is later + interpolated. We can use an end macro instead. Each level of + nesting should use a unique end macro. + + An end macro need not be defined until it is called. This fact + enables a nested macro definition to begin inside one macro and end + inside another. Consider the following example.(3) (*note Writing + Macros-Footnote-3::) + + .de m1 + . de m2 m3 + you + .. + .de m3 + Hello, + Joe. + .. + .de m4 + do + .. + .m1 + know? + . m3 + What + .m4 + .m2 + => Hello, Joe. What do you know? + + A nested macro definition _can_ be terminated with '..' and nested + macros _can_ reuse end macros, but these control lines must be + escaped multiple times for each level of nesting. The necessity of + this escaping and the utility of nested macro definitions will + become clearer when we employ macro parameters and consider the + behavior of copy mode in detail. + + 'de' defines a macro that inherits the compatibility mode enablement +status of its context (*note Implementation Differences::). Often it is +desirable to make a macro that uses 'groff' features callable from +contexts where compatibility mode is on; for instance, when writing +extensions to a historical macro package. To achieve this, +compatibility mode needs to be switched off while such a macro is +interpreted--without disturbing that state when it is finished. + + -- Request: .de1 name [end] + The 'de1' request defines a macro to be interpreted with + compatibility mode disabled. When NAME is called, compatibility + mode enablement status is saved; it is restored when the call + completes. Observe the extra backlash before the interpolation of + register 'xxx'; we'll explore this subject in *note Copy Mode::. + + .nr xxx 12345 + .de aa + The value of xxx is \\n[xxx]. + . br + .. + .de1 bb + The value of xxx is \\n[xxx]. + .. + .cp 1 + .aa + error-> warning: register '[' not defined + => The value of xxx is 0xxx]. + .bb + => The value of xxx is 12345. + + -- Request: .dei name [end] + -- Request: .dei1 name [end] + The 'dei' request defines a macro with its name and end macro + indirected through strings. That is, it interpolates strings named + NAME and END before performing the definition. + + The following examples are equivalent. + + .ds xx aa + .ds yy bb + .dei xx yy + + .de aa bb + + The 'dei1' request bears the same relationship to 'dei' as 'de1' + does to 'de'; it temporarily turns compatibility mode off when NAME + is called. + + -- Request: .am name [end] + -- Request: .am1 name [end] + -- Request: .ami name [end] + -- Request: .ami1 name [end] + 'am' appends subsequent input lines to macro NAME, extending its + definition, and otherwise working as 'de' does. + + To make the previously defined 'P' macro set indented instead of + block paragraphs, add the necessary code to the existing macro. + + .am P + .ti +5n + .. + + The other requests are analogous to their 'de' counterparts. The + 'am1' request turns off compatibility mode during interpretation of + the appendment. The 'ami' request appends indirectly, meaning that + strings NAME and END are interpolated with the resulting names used + before appending. The 'ami1' request is similar to 'ami', + disabling compatibility mode during interpretation of the appended + lines. + + Using 'trace.tmac', you can trace calls to 'de', 'de1', 'am', and +'am1'. You can also use the 'backtrace' request at any point desired to +troubleshoot tricky spots (*note Debugging::). + + *Note Strings::, for the 'als', 'rm', and 'rn' requests to create an +alias of, remove, and rename a macro, respectively. + + Macro identifiers share their name space with requests, strings, and +diversions; see *note Identifiers::. The 'am', 'as', 'da', 'de', 'di', +and 'ds' requests (together with their variants) create a new object +only if the name of the macro, diversion, or string is currently +undefined or if it is defined as a request; normally, they modify the +value of an existing object. *Note the description of the 'als' +request: als, for pitfalls when redefining a macro that is aliased. + + -- Request: .return [anything] + Exit a macro, immediately returning to the caller. If called with + an argument ANYTHING, exit twice--the current macro and the macro + one level higher. This is used to define a wrapper macro for + 'return' in 'trace.tmac'. + +* Menu: + +* Parameters:: +* Copy Mode:: + + +File: groff.info, Node: Writing Macros-Footnotes, Up: Writing Macros + + (1) *Note Copy Mode::. + + (2) While it is possible to define and call a macro '.', you can't +use it as an end macro: during a macro definition, '..' is never handled +as calling '.', even if '.de NAME .' explicitly precedes it. + + (3) Its structure is adapted from, and isomorphic to, part of a +solution by Tadziu Hoffman to the problem of reflowing text multiple +times to find an optimal configuration for it. +<https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html> + + +File: groff.info, Node: Parameters, Next: Copy Mode, Prev: Writing Macros, Up: Writing Macros + +5.24.1 Parameters +----------------- + +Macro calls and string interpolations optionally accept a list of +arguments; recall *note Calling Macros::. At the time such an +interpolation takes place, these "parameters" can be examined using a +register and a variety of escape sequences starting with '\$'. All such +escape sequences are interpreted even in copy mode, a fact we shall +motivate and explain below (*note Copy Mode::). + + -- Register: \n[.$] + The count of parameters available to a macro or string is kept in + this read-only register. The 'shift' request can change its value. + + Any individual parameter can be accessed by its position in the list +of arguments to the macro call, numbered from left to right starting at +1, with one of the following escape sequences. + + -- Escape sequence: \$n + -- Escape sequence: \$(nn + -- Escape sequence: \$[nnn] + Interpolate the Nth, NNth, or NNNth parameter. The first form + expects only a single digit (1<=N<=9)), the second two digits + (01<=NN<=99)), and the third any positive integer NNN. Macros and + strings accept an unlimited number of parameters. + + -- Request: .shift [n] + Shift the parameters N places (1 by default). This is a "left + shift": what was parameter I becomes parameter I-N. The parameters + formerly in positions 1 to N are no longer available. Shifting by + a non-positive amount performs no operation. The register '.$' is + adjusted accordingly. + + In practice, parameter interpolations are usually seen prefixed with +an extra escape character. This is because the '\$' family of escape +sequences is interpreted even in copy mode.(1) (*note +Parameters-Footnote-1::) + + -- Escape sequence: \$* + -- Escape sequence: \$@ + -- Escape sequence: \$^ + In some cases it is convenient to interpolate all of the parameters + at once (to pass them to a request, for instance). The '\$*' + escape concatenates the parameters, separating them with spaces. + '\$@' is similar, concatenating the parameters, surrounding each + with double quotes and separating them with spaces. If not in + compatibility mode, the interpolation depth of double quotes is + preserved (*note Calling Macros::). '\$^' interpolates all + parameters as if they were arguments to the 'ds' request. + + .de foo + . tm $1='\\$1' + . tm $2='\\$2' + . tm $*='\\$*' + . tm $@='\\$@' + . tm $^='\\$^' + .. + .foo " This is a "test" + error-> $1=' This is a ' + error-> $2='test"' + error-> $*=' This is a test"' + error-> $@='" This is a " "test""' + error-> $^='" This is a "test"' + + '\$*' is useful when writing a macro that doesn't need to + distinguish its arguments, or even to not interpret them; examples + include macros that produce diagnostic messages by wrapping the + 'tm' or 'ab' requests. Use '\$@' when writing a macro that may + need to shift its parameters and/or wrap a macro or request that + finds the count significant. If in doubt, prefer '\$@' to '\$*'. + An application of '\$^' is seen in 'trace.tmac', which redefines + some requests and macros for debugging purposes. + + -- Escape sequence: \$0 + Interpolate the name by which the macro being interpreted was + called. The 'als' request can cause a macro to have more than one + name. Applying string interpolation to a macro does not change + this name. + + .de foo + . tm \\$0 + .. + .als bar foo + . + .de aaa + . foo + .. + .de bbb + . bar + .. + .de ccc + \\*[foo]\\ + .. + .de ddd + \\*[bar]\\ + .. + . + .aaa + error-> foo + .bbb + error-> bar + .ccc + error-> ccc + .ddd + error-> ddd + + +File: groff.info, Node: Parameters-Footnotes, Up: Parameters + + (1) If they were not, parameter interpolations would be similar to +command-line parameters--fixed for the entire duration of a 'roff' +program's run. The advantage of interpolating '\$' escape sequences +even in copy mode is that they can interpolate different contents from +one call to the next, like function parameters in a procedural language. +The additional escape character is the price of this power. + + +File: groff.info, Node: Copy Mode, Prev: Parameters, Up: Writing Macros + +5.24.2 Copy Mode +---------------- + +When GNU 'troff' processes certain requests, most importantly those +which define or append to a macro or string, it does so in "copy mode": +it copies the characters of the definition into a dedicated storage +region, interpolating the escape sequences '\n', '\g', '\$', '\*', '\V', +and '\?' normally; interpreting '\<RET>' immediately; discarding +comments '\"' and '\#'; interpolating the current leader, escape, or tab +character with '\a', '\e', and '\t', respectively; and storing all other +escape sequences in an encoded form. + + The complement of copy mode--a 'roff' formatter's behavior when not +defining or appending to a macro, string, or diversion--where all macros +are interpolated, requests invoked, and valid escape sequences processed +immediately upon recognition, can be termed "interpretation mode". + + -- Escape sequence: \\ + The escape character, '\' by default, can escape itself. This + enables you to control whether a given '\n', '\g', '\$', '\*', + '\V', or '\?' escape sequence is interpreted at the time the macro + containing it is defined, or later when the macro is called.(1) + (*note Copy Mode-Footnote-1::) + + .nr x 20 + .de y + .nr x 10 + \&\nx + \&\\nx + .. + .y + => 20 10 + + You can think of '\\' as a "delayed" backslash; it is the escape + character followed by a backslash from which the escape character + has removed its special meaning. Consequently, '\\' is not an + escape sequence in the usual sense. In any escape sequence '\X' + that GNU 'troff' does not recognize, the escape character is + ignored and X is output. An unrecognized escape sequence causes a + warning in category 'escape', with two exceptions--'\\' is the + first. + + -- Escape sequence: \. + '\.' escapes the control character. It is similar to '\\' in that + it isn't a true escape sequence. It is used to permit nested macro + definitions to end without a named macro call to conclude them. + Without a syntax for escaping the control character, this would not + be possible. + + .de m1 + foo + . + . de m2 + bar + \\.. + . + .. + .m1 + .m2 + => foo bar + + The first backslash is consumed while the macro is read, and the + second is interpreted when macro 'm1' is called. + + 'roff' documents should not use the '\\' or '\.' character sequences +outside of copy mode; they serve only to obfuscate the input. Use '\e' +to represent the escape character, '\[rs]' to obtain a backslash glyph, +and '\&' before '.' and ''' where GNU 'troff' expects them as control +characters if you mean to use them literally (recall *note Requests and +Macros::). + + Macro definitions can be nested to arbitrary depth. The mechanics of +parsing the escape character have significant consequences for this +practice. + + .de M1 + \\$1 + . de M2 + \\\\$1 + . de M3 + \\\\\\\\$1 + \\\\.. + . M3 hand. + \\.. + . M2 of + .. + This understeer is getting + .M1 out + => This understeer is getting out of hand. + + Each escape character is interpreted twice--once in copy mode, when +the macro is defined, and once in interpretation mode, when the macro is +called. As seen above, this fact leads to exponential growth in the +quantity of escape characters required to delay interpolation of '\n', +'\g', '\$', '\*', '\V', and '\?' at each nesting level, which can be +daunting. GNU 'troff' offers a solution. + + -- Escape sequence: \E + '\E' represents an escape character that is not interpreted in copy + mode. You can use it to ease the writing of nested macro + definitions. + + .de M1 + . nop \E$1 + . de M2 + . nop \E$1 + . de M3 + . nop \E$1 + \\\\.. + . M3 better. + \\.. + . M2 bit + .. + This vehicle handles + .M1 a + => This vehicle handles a bit better. + + Observe that because '\.' is not a true escape sequence, we can't + use '\E' to keep '..' from ending a macro definition prematurely. + If the multiplicity of backslashes complicates maintenance, use end + macros. + + '\E' is also convenient to define strings containing escape + sequences that need to work when used in copy mode (for example, as + macro arguments), or which will be interpolated at varying macro + nesting depths. We might define strings to begin and end + superscripting as follows.(2) (*note Copy Mode-Footnote-2::) + + .ds { \v'-.9m\s'\En[.s]*7u/10u'+.7m' + .ds } \v'-.7m\s0+.9m' + + When the 'ec' request is used to redefine the escape character, + '\E' also makes it easier to distinguish the semantics of an escape + character from the other meaning(s) its character might have. + Consider the use of an unusual escape character, '-'. + + .nr a 1 + .ec - + .de xx + --na + .. + .xx + => -na + + This result may surprise you; some people expect '1' to be output + since register 'a' has clearly been defined with that value. What + has happened? The robotic replacement of '\' with '-' has led us + astray. You might recognize the sequence '--' more readily with + the default escape character as '\-', the special character escape + sequence for the minus sign glyph. + + .nr a 1 + .ec - + .de xx + -Ena + .. + .xx + => 1 + + +File: groff.info, Node: Copy Mode-Footnotes, Up: Copy Mode + + (1) Compare this to the '\def' and '\edef' commands in TeX. + + (2) These are lightly adapted from the 'groff' implementation of the +'ms' macros. + + +File: groff.info, Node: Page Motions, Next: Drawing Geometric Objects, Prev: Writing Macros, Up: GNU troff Reference + +5.25 Page Motions +================= + +*Note Manipulating Spacing::, for a discussion of the most commonly used +request for vertical motion, 'sp', which spaces downward by one vee. + + -- Request: .mk [reg] + -- Request: .rt [dist] + You can "mark" a location on a page for subsequent "return". 'mk' + takes an argument, a register name in which to store the current + page location. If given no argument, it stores the location in an + internal register. This location can be used later by the 'rt' or + the 'sp' requests (or the '\v' escape). + + The 'rt' request returns _upward_ to the location marked with the + last 'mk' request. If used with an argument, it returns to a + vertical position DIST from the top of the page (no previous call + to 'mk' is necessary in this case). The default scaling unit is + 'v'. + + If a page break occurs between a 'mk' request and its matching 'rt' + request, the 'rt' request is silently ignored. + + A simple implementation of a macro to set text in two columns + follows. + + .nr column-length 1.5i + .nr column-gap 4m + .nr bottom-margin 1m + . + .de 2c + . br + . mk + . ll \\n[column-length]u + . wh -\\n[bottom-margin]u 2c-trap + . nr right-side 0 + .. + . + .de 2c-trap + . ie \\n[right-side] \{\ + . nr right-side 0 + . po -(\\n[column-length]u + \\n[column-gap]u) + . \" remove trap + . wh -\\n[bottom-margin]u + . \} + . el \{\ + . \" switch to right side + . nr right-side 1 + . po +(\\n[column-length]u + \\n[column-gap]u) + . rt + . \} + .. + + Now let us apply our two-column macro. + + .pl 1.5i + .ll 4i + This is a small test that shows how the + rt request works in combination with mk. + + .2c + Starting here, text is typeset in two columns. + Note that this implementation isn't robust + and thus not suited for a real two-column + macro. + => This is a small test that shows how the + => rt request works in combination with mk. + => + => Starting here, isn't robust + => text is typeset and thus not + => in two columns. suited for a + => Note that this real two-column + => implementation macro. + + Several escape sequences enable fine control of movement about the +page. + + -- Escape sequence: \v'expr' + Vertically move the drawing position. EXPR indicates the magnitude + of motion: positive is downward and and negative upward. The + default scaling unit is 'v'. The motion is relative to the current + drawing position unless EXPR begins with the boundary-relative + motion operator '|'. *Note Numeric Expressions::. + + Text processing continues at the new drawing position; usually, + vertical motions should be in balanced pairs to avoid a confusing + page layout. + + '\v' will not spring a vertical position trap. This can be useful; + for example, consider a page bottom trap macro that prints a marker + in the margin to indicate continuation of a footnote. *Note + Traps::. + + A few escape sequences that produce vertical motion are unusual. +They are thought to originate early in AT&T 'nroff' history to achieve +super- and subscripting by half-line motions on line printers and +teletypewriters before the phototypesetter made more precise positioning +available. They are reckoned in ems--not vees--to maintain continuity +with their original purpose of moving relative to the size of the type +rather than the distance between text baselines (vees).(1) (*note Page +Motions-Footnote-1::) + + -- Escape sequence: \r + -- Escape sequence: \u + -- Escape sequence: \d + Move upward 1m, upward .5m, and downward .5m, respectively. + +Let us see these escape sequences in use. + + Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU. + + In the foregoing we have paired '\u' and '\d' to typeset a +superscript, and later a full em negative ("reverse") motion to place a +superscript above a subscript. A numeral-width horizontal motion escape +sequence aligns the proton and nucleon numbers, while '\k' marks a +horizontal position to which '\h' returns so that we could stack them. +(We shall discuss these horizontal motion escape sequences presently.) +In serious applications, we often want to alter the type size of the +-scripts and to fine-tune the vertical motions, as the 'groff' 'ms' +package does with its super- and subscripting string definitions. + + -- Escape sequence: \h'expr' + Horizontally move the drawing position. EXPR indicates the + magnitude of motion: positive is rightward and negative leftward. + The default scaling unit is 'm'. The motion is relative to the + current drawing position unless EXPR begins with the + boundary-relative motion operator '|'. *Note Numeric + Expressions::. + + The following string definition sets the TeX logo.(2) (*note Page +Motions-Footnote-2::) + + .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\" + + There are a number of special-case escape sequences for horizontal +motion. + + -- Escape sequence: \<SP> + Move right one word space. (The input is a backslash followed by a + space.) This escape sequence can be thought of as a + non-adjustable, unbreakable space. Usually you want '\~' instead; + see *note Manipulating Filling and Adjustment::. + + -- Escape sequence: \| + Move one-sixth em to the right on typesetting output devices. If a + glyph named '\|' is defined in the current font, its width is used + instead, even on terminal output devices. + + -- Escape sequence: \^ + Move one-twelfth em to the right on typesetting output devices. If + a glyph named '\^' is defined in the current font, its width is + used instead, even on terminal output devices. + + -- Escape sequence: \0 + Move right by the width of a numeral in the current font. + + Horizontal motions are not discarded at the end of an output line as +word spaces are. *Note Breaking::. + + -- Escape sequence: \w'anything' + -- Register: \n[st] + -- Register: \n[sb] + -- Register: \n[rst] + -- Register: \n[rsb] + -- Register: \n[ct] + -- Register: \n[ssc] + -- Register: \n[skw] + Interpolate the width of ANYTHING in basic units. This escape + sequence allows several properties of formatted output to be + measured without writing it out. + + The length of the string 'abc' is \w'abc'u. + => The length of the string 'abc' is 72u. + + ANYTHING is processed in a dummy environment: this means that font + and type size changes, for example, may occur within it without + affecting subsequent output. + + After each use, '\w' sets several registers. + + 'st' + 'sb' + The maximum vertical displacements of the text baseline above + and below, respectively. The sign convention is opposite that + of relative vertical motions; that is, depth below the + (original) baseline is negative. These registers are + incorrectly documented in the AT&T 'troff' manual as "the + highest and lowest extent of [the argument to '\w'] relative + to the baseline". + + 'rst' + 'rsb' + Like 'st' and 'sb', but taking account of the heights and + depths of glyphs. In other words, these registers store the + highest and lowest vertical positions attained by ANYTHING, + doing what AT&T 'troff' documented 'st' and 'sb' as doing. + + 'ct' + Characterizes the geometry of glyphs occurring in ANYTHING. + + 0 + only short glyphs, no descenders or tall glyphs + + 1 + at least one descender + + 2 + at least one tall glyph + + 3 + at least one each of a descender and a tall glyph + + 'ssc' + The amount of horizontal space (possibly negative) that should + be added to the last glyph before a subscript. + + 'skw' + How far to right of the center of the last glyph in the '\w' + argument, the center of an accent from a roman font should be + placed over that glyph. + + -- Escape sequence: \kp + -- Escape sequence: \k(ps + -- Escape sequence: \k[position] + Store the current horizontal position in the _input_ line in a + register with the name POSITION (one-character name P, + two-character name PS). Use this, for example, to return to the + beginning of a string for highlighting or other decoration. + + -- Register: \n[hp] + The current horizontal position at the input line. + + -- Register: \n[.k] + A read-only register containing the current horizontal output + position (relative to the current indentation). + + -- Escape sequence: \o'abc...' + Overstrike the glyphs of characters A, B, C, ...; the glyphs are + centered, written, and the drawing position advanced by the widest + of the glyphs. + + -- Escape sequence: \zc + Format the character C with zero width; that is, without advancing + the drawing position. Use '\z' to overstrike glyphs aligned to + their left edges, in contrast to '\o''s centering. + + -- Escape sequence: \Z'anything' + Save the drawing position, format ANYTHING, then restore it. Tabs + and leaders in the argument are ignored with an error diagnostic. + + We might implement a strike-through macro thus. + + .de ST + .nr width \w'\\$1' + \Z@\v'-.25m'\l'\\n[width]u'@\\$1 + .. + . + This is + .ST "a test" + an actual emergency! + + +File: groff.info, Node: Page Motions-Footnotes, Up: Page Motions + + (1) At the 'grops' defaults of 10-point type on 12-point vertical +spacing, the difference between half a vee and half an em can be subtle: +large spacings like '.vs .5i' make it obvious. + + (2) *Note Strings::, for an explanation of the trailing '\"'. + + +File: groff.info, Node: Drawing Geometric Objects, Next: Traps, Prev: Page Motions, Up: GNU troff Reference + +5.26 Drawing Geometric Objects +============================== + +A few of the formatter's escape sequences draw lines and other geometric +objects. Combined with each other and with page motion commands (*note +Page Motions::), a wide variety of figures is possible. For complex +drawings, these operations can be cumbersome; the preprocessors 'gpic' +or 'ggrn' are typically used instead. + + The '\l' and '\L' escape sequences draw horizontal and vertical +sequences of glyphs, respectively. Even the simplest of output devices +supports them. + + -- Escape sequence: \l'l' + -- Escape sequence: \l'lc' + Draw a horizontal line of length L from the drawing position. + Rightward motion is positive. Afterward, the drawing position is + at the right end of the line. The default scaling unit is 'm'. + + The optional second parameter C is a character with which to draw + the line. The default is the baseline rule special character, + '\[ru]'. + + If C is a valid scaling unit, put '\&' after L to disambiguate the + input. + + .de textbox + \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' + .. + + The foregoing outputs a box rule (a vertical line), the text + argument(s), and another box rule. We employ the boundary-relative + motion operator '|'. Finally, the line-drawing escape sequences + draw a radical extender (a form of overline) and an underline from + the drawing position to the position coresponding to beginning of + the _input_ line. The drawing position returns to just after the + right-hand box rule because the lengths of the drawn lines are + negative, as noted above. + + -- Escape sequence: \L'l' + -- Escape sequence: \L'lc' + Draw a vertical line of length L from the drawing position. + Downward motion is positive. The default scaling unit is 'v'. The + default character is the box rule, '\[br]'. As with vertical + motion escape sequences, text processing continues where the line + ends. '\L' is otherwise similar to '\l'. + + $ nroff <<EOF + This is a \L'3v'test. + EOF + => This is a + => | + => | + => |test. + + When writing text, the drawing position is at the text baseline; + recall *note Page Geometry::. + + The '\D' escape sequence provides "drawing commands" that direct the +output device to render geometrical objects rather than glyphs. +Specific devices may support only a subset, or may feature additional +ones; consult the man page for the output driver in use. Terminal +devices in particular implement almost none. *Note Graphics Commands::. + + Rendering starts at the drawing position; when finished, the drawing +position is left at the rightmost point of the object, even for closed +figures, except where noted. GNU 'troff' draws stroked (outlined) +objects with the stroke color, and shades filled ones with the fill +color. *Note Colors::. Coordinates H and V are horizontal and vertical +motions relative to the drawing position or previous point in the +command. The default scaling unit for horizontal measurements (and +diameters of circles) is 'm'; for vertical ones, 'v'. + + Circles, ellipses, and polygons can be drawn filled or stroked. +These are independent properties; if you want a filled, stroked figure, +you must draw the same figure twice using each drawing command. A +filled figure is always smaller than an outlined one because the former +is drawn only within its defined area, whereas strokes have a line +thickness (set with '\D't''). + + \h'1i'\v'1i'\ + \# increase line thickness + \Z'\D't 5p''\ + \# draw stroked (unfilled) polygon + \Z'\D'p 3 3 -6 0''\ + \# draw filled (solid) polygon + \Z'\D'P 3 3 -6 0'' + + -- Escape sequence: \D'command argument ...' + Drawing command escape sequence parameters begin with an ordinary + character, COMMAND, selecting the type of object to be drawn, + followed by ARGUMENTs whose meaning is determined by COMMAND. + + '\D'~ H1 V1 ... HN VN'' + Draw a B-spline to each point in sequence, leaving the drawing + position at (HN, VN). + + '\D'a HC VC H V'' + Draw a circular arc centered at (HC, VC) counterclockwise from + the drawing position to a point (H, V) relative to the center. + (1) (*note Drawing Geometric Objects-Footnote-1::) + + '\D'c D'' + Draw a circle of diameter D with its leftmost point at the + drawing position. + + '\D'C D'' + As '\D'C ...'', but the circle is filled. + + '\D'e H V'' + Draw an ellipse of width H and height V with its leftmost + point at the drawing position. + + '\D'E X Y'' + As '\D'e ...'', but the ellipse is filled. + + '\D'l DX DY'' + Draw line from the drawing position to (H, V). + + The following is a macro for drawing a box around a text + argument; for simplicity, the box margin is a fixed at 0.2m. + + .de TEXTBOX + . nr @wd \w'\\$1' + \h'.2m'\ + \h'-.2m'\v'(.2m - \\n[rsb]u)'\ + \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ + \D'l (\\n[@wd]u + .4m) 0'\ + \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ + \D'l -(\\n[@wd]u + .4m) 0'\ + \h'.2m'\v'-(.2m - \\n[rsb]u)'\ + \\$1\ + \h'.2m' + .. + + The argument is measured with the '\w' escape sequence. Its + width is stored in register '@wd'. '\w' also sets the + registers 'rst' and 'rsb'; these contain its maximum vertical + extents of the argument. Then, four lines are drawn to form a + box, offset by the box margin. + + '\D'p H1 V1 ... HN VN'' + Draw polygon with vertices at drawing position and each point + in sequence. GNU 'troff' closes the polygon by drawing a line + from (HN, VN) back to the initial drawing position. + Afterward, the drawing position is left at (HN, VN). + + '\D'P DX1 DY1 DX2 DY2 ...'' + As '\D'P ...'', but the polygon is filled. + + The following macro is like the '\D'l'' example, but shades + the box. We draw the box before writing the text because + colors in GNU 'troff' have no transparency; in othe opposite + order, the filled polygon would occlude the text. + + .de TEXTBOX + . nr @wd \w'\\$1' + \h'.2m'\ + \h'-.2m'\v'(.2m - \\n[rsb]u)'\ + \M[lightcyan]\ + \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ + (\\n[@wd]u + .4m) 0 \ + 0 (\\n[rst]u - \\n[rsb]u + .4m) \ + -(\\n[@wd]u + .4m) 0'\ + \h'.2m'\v'-(.2m - \\n[rsb]u)'\ + \M[]\ + \\$1\ + \h'.2m' + .. + + '\D't N'' + Set the stroke thickness of geometric objects to N basic + units. A zero N selects the minimal supported thickness. A + negative N selects a thickness proportional to the type size; + this is the default. + + In a hazy penumbra between text rendering and drawing commands we +locate the bracket-building escape sequence, '\b'. It can assemble +apparently large glyphs by vertically stacking ordinary ones. + + -- Escape sequence: \b'contents' + Pile and center a sequence of glyphs vertically on the output line. + "Piling" stacks glyphs corresponding to each character in CONTENTS, + read from left to right, and placed from top to bottom. GNU + 'troff' separates the glyphs vertically by 1m, and the pile itself + is centered 0.5m above the text baseline. The horizontal drawing + position is then advanced by the width of the widest glyph in the + pile. + + This rather inflexible positioning algorithm doesn't work with the + 'dvi' output device since its bracket pieces vary in height. + Instead, use the 'geqn' preprocessor. + + *note Manipulating Spacing:: describes how to adjust the vertical + spacing of the output line with the '\x' escape sequence. + + The application of '\b' that lends its name is construction of + brackets, braces, and parentheses when typesetting mathematics. We + might construct a large opening (left) brace as follows. + + \b'\[lt]\[bv]\[lk]\[bv]\[lb]' + + See 'groff_char(7)' for a list of special character identifiers. + + +File: groff.info, Node: Drawing Geometric Objects-Footnotes, Up: Drawing Geometric Objects + + (1) (HC, VC) is adjusted to the point nearest the perpendicular +bisector of the arc's chord. + + +File: groff.info, Node: Deferring Output, Next: Traps, Prev: Drawing Geometric Objects, Up: GNU troff Reference + +5.27 Deferring Output +===================== + +A few 'roff' language elements are generally not used in simple +documents, but arise as page layouts become more sophisticated and +demanding. "Environments" collect formatting parameters like line +length and typeface. A "diversion" stores formatted output for later +use. A "trap" is a condition on the input or output, tested +automatically by the formatter, that is associated with a macro, causing +it to be called when that condition is fulfilled. + + Footnote support often exercises all three of the foregoing features. +A simple implementation might work as follows. A pair of macros is +defined: one starts a footnote and the other ends it. The author calls +the first macro where a footnote marker is desired. The macro +establishes a diversion so that the footnote text is collected at the +place in the body text where its corresponding marker appears. An +environment is created for the footnote so that it is set at a smaller +typeface. The footnote text is formatted in the diversion using that +environment, but it does not yet appear in the output. The document +author calls the footnote end macro, which returns to the previous +environment and ends the diversion. Later, after much more body text in +the document, a trap, set a small distance above the page bottom, is +sprung. The macro called by the trap draws a line across the page and +emits the stored diversion. Thus, the footnote is rendered. + + Diversions and traps make the text formatting process non-linear. +Let us imagine a set of text lines or paragraphs labelled 'A', 'B', and +so on. If we set up a trap that produces text 'T' (as a page footer, +say), and we also use a diversion to store the formatted text 'D', then +a document with input text in the order 'A B C D E F' might render as 'A +B C E T F'. The diversion 'D' will never be output if we do not call +for it. + + Environments of themselves are not a source of non-linearity in +document formatting: environment switches have immediate effect. One +could always write a macro to change as many formatting parameters as +desired with a single convenient call. But because diversions can be +nested and macros called by traps that are sprung by other trap-called +macros, they may be called upon in varying contexts. For example, +consider a page header that is always to be set in Helvetica. A +document that uses Times for most of its body text, but Courier for +displayed code examples, poses a challenge if a page break occurs in the +middle of a code display; if the header trap assumes that the "previous +font" is always Times, the rest of the example will be formatted in the +wrong typeface. One could carefully save all formatting parameters upon +entering the trap and restore them upon leaving it, but this is verbose, +error-prone, and not future-proof as the 'groff' language develops. +Environments save us considerable effort. + + +File: groff.info, Node: Traps, Next: Diversions, Prev: Deferring Output, Up: GNU troff Reference + +5.28 Traps +========== + +"Traps" are locations in the output or conditions on the input that, +when reached or fulfilled, call a specified macro. These traps can +occur at a given location on the page, at a given location in the +current diversion (together, these are known as vertical position +traps), at a blank line, at a line with leading space characters, after +a quantity of input lines, or at the end of input. Macros called by +traps are passed no arguments. Setting a trap is also called "planting" +one. It is said that a trap is "sprung" if its condition is fulfilled. + +* Menu: + +* Vertical Position Traps:: +* Diversion Traps:: +* Input Line Traps:: +* Blank Line Traps:: +* Leading Space Traps:: +* End-of-input Traps:: + + +File: groff.info, Node: Vertical Position Traps, Next: Page Location Traps, Prev: Traps, Up: Traps + +5.28.1 Vertical Position Traps +------------------------------ + +A "vertical position trap" calls a macro when the formatter's vertical +drawing position reaches or passes, in the downward direction, a certain +location on the output page or in a diversion. Its applications include +setting page headers and footers, body text in multiple columns, and +footnotes. + + -- Request: .vpt [flag] + -- Register: \n[.vpt] + Enable vertical position traps if FLAG is non-zero or absent; + disable them otherwise. Vertical position traps are those set by + the 'wh' request or by 'dt' within a diversion. The parameter that + controls whether vertical position traps are enabled is global. + Initially, vertical position traps are enabled. The current value + is stored in the '.vpt' read-only register. + + A page can't be ejected if 'vpt' is set to zero; see *note The + Implicit Page Trap::. + +* Menu: + +* Page Location Traps:: +* The Implicit Page Trap:: +* Diversion Traps:: + + +File: groff.info, Node: Page Location Traps, Next: The Implicit Page Trap, Prev: Vertical Position Traps, Up: Vertical Position Traps + +5.28.1.1 Page Location Traps +............................ + +A "page location trap" is a vertical position trap that applies to the +page; that is, to undiverted output. Many can be present; manage them +with the 'wh' and 'ch' requests. + + -- Request: .wh dist [name] + Plant macro NAME as page location trap at DIST. The default + scaling unit is 'v'. 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. It is not possible to plant a + trap less than one basic unit from the page bottom: a DIST of '-0' + is interpreted as '0', the top of the page.(1) (*note Page + Location Traps-Footnote-1::) An existing _visible_ trap (see below) + at DIST is removed; this is 'wh''s sole function if NAME is + missing. + + A trap is sprung only if it is "visible", meaning that its location + is reachable on the page(2) (*note Page Location + Traps-Footnote-2::) and it is not hidden by another trap at the + same location already planted there. + + A macro package might set headers and footers as follows; this + example configures vertical margins of one inch to the body text, + and one half-inch to the titles. Observe the use of the no-break + control character with 'sp' request to position our text baselines, + and the page number character '%' used with the 'tl' request. + + .\" hdfo.roff + .de hd \" page header + ' sp .5i + ' tl '\\*(Ti''\\*(Da' \" title and date strings + ' sp .5i + .. + .de fo \" page footer + ' sp .5i + . tl ''%'' + . bp + .. + .wh 0 hd \" trap at top of the page + .wh -1i fo \" trap 1 inch from bottom + + To use these traps, copy the above (or load it from a file with the + 'so' or 'mso' requests), then set up the strings it uses. + + .so hdfo.roff + .ds Ti Final Report\" + .ds Da 21 May 2023\" + .ti + On 5 August of last year, + this committee tasked me with the investigation of the + CFIT (controlled flight into terrain) incident of + .\" ...and so on... + + A trap above the top or at or below the bottom of the page can be + made visible by either moving it into the page area or increasing + the page length so that the trap is on the page. Negative trap + values always use the _current_ page length; they are not converted + to an absolute vertical position. We can use the 'ptr' request to + dump our page location traps to the standard error stream (*note + Debugging::). Their positions are reported in basic units; an + 'nroff' device example follows. + + .pl 5i + .wh -1i xx + .ptr + error-> xx -240 + .pl 100i + .ptr + error-> xx -240 + + It is possible to have more than one trap at the same location + (although only one at a time can be visible); to achieve this, the + traps must be defined at different locations, then moved to the + same place with the 'ch' request. In the following example, the + many empty lines caused by the 'bp' request are not shown in the + output. + + .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] + The read-only register '.t' holds the distance to the next vertical + position trap. If there are no traps between the current position + and the bottom of the page, it contains the distance to the page + bottom. Within a diversion, in the absence of a diversion trap, + this distance is the largest representable integer in basic + units--effectively infinite. + + -- Request: .ch name [dist] + Change the location of a trap by moving macro NAME to new location + DIST, or by unplanting it altogether if DIST is absent. The + default scaling unit is 'v'. Parameters to 'ch' are specified in + the opposite order from 'wh'. If NAME is the earliest planted + macro of multiple traps at the same location, (re)moving it from + that location exposes the macro next least recently planted at the + same place.(3) (*note Page Location Traps-Footnote-3::) + + Changing a trap's location is useful for building up footnotes in a + diversion to allow more space at the bottom of the page for them. + + The same macro can be installed simultaneously at multiple locations; +however, only the earliest-planted instance--that has not yet been +deleted with 'wh'--will be moved by 'ch'. The following example (using +an 'nroff' device) illustrates this behavior. Blank lines have been +elided from the output. + + .de T + Trap sprung at \\n(nlu. + .br + .. + .wh 1i T + .wh 2i T + foo + .sp 11i + .bp + .ch T 4i + bar + .sp 11i + .bp + .ch T 5i + baz + .sp 11i + .bp + .wh 5i + .ch T 6i + qux + .sp 11i + => foo + => Trap sprung at 240u. + => Trap sprung at 480u. + => bar + => Trap sprung at 480u. + => Trap sprung at 960u. + => baz + => Trap sprung at 480u. + => Trap sprung at 1200u. + => qux + => Trap sprung at 1440u. + + -- Register: \n[.ne] + The read-only register '.ne' contains the amount of space that was + needed in the last 'ne' request that caused a trap to be sprung; it + is useful in conjunction with the '.trunc' register. *Note Page + Control::. Since the '.ne' register is set only by traps, it + doesn't make sense to interpolate it outside of macros called by + traps. + + -- Register: \n[.trunc] + A read-only register containing the amount of vertical space + truncated from an 'sp' request 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 set only by traps, it doesn't make sense to + interpolate it outside of macros called by traps. + + -- Register: \n[.pe] + This Boolean-valued, read-only register interpolates 1 while a page + is being ejected, and 0 otherwise. + + In the following example, we plant the same trap at the top and the + bottom of the page. We also make the trap report its name and the + vertical drawing position. + + .de T + .tm \\$0: page \\n%, nl=\\n[nl] .pe=\\n[.pe] + .. + .ll 46n + .wh 0 T + .wh -1v T + Those who can make you believe absurdities can make you + commit atrocities. \[em] Voltaire + error-> T: page 1, nl=0 .pe=0 + error-> T: page 1, nl=2600 .pe=1 + => Those who can make you believe absurdities can + => make you commit atrocities. -- Voltaire + + When designing macros, keep in mind that diversions and traps do +normally interact. For example, if a trap calls a header macro (while +outputting a diversion) that tries to change the font on the current +page, the effect is not 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.info, Node: Page Location Traps-Footnotes, Up: Page Location Traps + + (1) *Note The Implicit Page Trap::. + + (2) A trap planted at '20i' or '-30i' will not be sprung on a page of +length '11i'. + + (3) It may help to think of each trap location as maintaining a +queue; 'wh' operates on the head of the queue, and 'ch' operates on its +tail. Only the trap at the head of the queue is visible. + + +File: groff.info, Node: The Implicit Page Trap, Next: Diversion Traps, Prev: Page Location Traps, Up: Vertical Position Traps + +5.28.1.2 The Implicit Page Trap +............................... + +If, after starting GNU 'troff' without loading a macro package, you use +the 'ptr' request to dump a list of the active traps to the standard +error stream,(1) (*note The Implicit Page Trap-Footnote-1::) nothing is +reported. Yet the '.t' register will report a steadily decreasing value +with every output line your document produces, and once the value of +'.t' gets to within '.V' of zero, you will notice that something +trap-like happens--the page is ejected, a new one begins, and the value +of '.t' becomes large once more. + + This "implicit page trap" always exists in the top-level +diversion;(2) (*note The Implicit Page Trap-Footnote-2::) it works like +a trap in some ways but not others. Its purpose is to eject the current +page and start the next one. It has no name, so it cannot be moved or +deleted with 'wh' or 'ch' requests. You cannot hide it by placing +another trap at its location, and can move it only by redefining the +page length with 'pl'. Its operation is suppressed when vertical page +traps are disabled with GNU 'troff''s 'vpt' request. + + +File: groff.info, Node: The Implicit Page Trap-Footnotes, Up: The Implicit Page Trap + + (1) *Note Debugging::. + + (2) *Note Diversions::. + + +File: groff.info, Node: Diversion Traps, Next: Input Line Traps, Prev: The Implicit Page Trap, Up: Vertical Position Traps + +5.28.1.3 Diversion Traps +........................ + +A diversion is not formatted in the context of a page, so it lacks page +location traps; instead it can have a "diversion trap". There can exist +at most one such vertical position trap per diversion. + + -- Request: .dt [dist name] + Set a trap _within_ a diversion at location DIST, which is + interpreted relative to diversion rather than page boundaries. If + invoked with fewer than two arguments, any diversion trap in the + current diversion is removed. The register '.t' works within + diversions. It is an error to invoke 'dt' in the top-level + diversion. *Note Diversions::. + + +File: groff.info, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps + +5.28.2 Input Line Traps +----------------------- + + -- Request: .it [n name] + -- Request: .itc [n name] + Set an input line trap, calling macro NAME after processing the + next N productive input lines (recall *note Manipulating Filling + and Adjustment::). Any existing input line trap in the environment + is replaced. Without arguments, 'it' and 'itc' clear any input + line trap that has not yet sprung. + + Consider a macro '.ST S N' which sets the next N input lines in the + font style S. + + .de ST \" Use style $1 for next $2 text lines. + . it \\$2 ES + . ft \\$1 + .. + .de ES \" end ST + . ft R + .. + .ST I 1 + oblique + face + .ST I 1 + oblique\c + face + => oblique face obliqueface (second "face" upright) + + Unlike the 'ce' and 'rj' requests, 'it' counts lines interrupted + with the '\c' escape sequence separately (*note Line + Continuation::); 'itc' does not. To see the difference, let's + change the previous example to use 'itc' instead. + + ... + . itc \\$2 ES + ... + => oblique face obliqueface (second "face" oblique) + + You can think of the 'ce' and 'rj' requests as implicitly creating + an input line trap with 'itc' that schedules a break when the trap + is sprung. + + .de BR + . br + . internal: disable centering-without-filling + .. + . + .de ce + . if \\n[.br] .br + . itc \\$1 BR + . internal: enable centering-without-filling + .. + + Let us consider in more detail the sorts of input lines that are or + are not "productive". + + .de Trap + TRAP SPRUNG + .. + .de Mac + .if r a \l'5n' + .. + .it 2 Trap + . + foo + .Mac + bar + baz + .it 1 Trap + .sp \" moves, but does not write or draw + qux + .itc 1 Trap + \h'5n'\c \" moves, but does not write or draw + jat + + When 'Trap' gets called depends on whether the 'a' register is + defined; the control line with the 'if' request may or may not + produce written output. We also see that the spacing request 'sp', + while certainly affecting the output, does not spring the input + line trap. Similarly, the horizontal motion escape sequence '\h' + also affected the output, but was not "written". Observe that we + had to follow it with '\c' and use 'itc' to prevent the newline at + the end of the text line from causing a word break, which, like an + ordinary space character, counts as written output. + + $ groff -Tascii input-trap-example.groff + => foo bar TRAP SPRUNG baz + => + => qux TRAP SPRUNG jat TRAP SPRUNG + $ groff -Tascii -ra1 input-trap-example.groff + => foo _____ TRAP SPRUNG bar baz + => + => qux TRAP SPRUNG jat TRAP SPRUNG + + Input line traps are associated with the environment (*note +Environments::); switching to another environment suspends the current +input line trap, and going back resumes it, restoring the count of +qualifying lines enumerated in that environment. + + +File: groff.info, Node: Blank Line Traps, Next: Leading Space Traps, Prev: Input Line Traps, Up: Traps + +5.28.3 Blank Line Traps +----------------------- + + -- Request: .blm [name] + Set a blank line trap, calling the macro NAME when GNU 'troff' + encounters a blank line in an input file, instead of the usual + behavior (*note Breaking::). A line consisting only of spaces is + also treated as blank and subject to this trap. If no argument is + supplied, the default blank line behavior is (re-)established. + + +File: groff.info, Node: Leading Space Traps, Next: End-of-input Traps, Prev: Blank Line Traps, Up: Traps + +5.28.4 Leading Space Traps +-------------------------- + + -- Request: .lsm [name] + -- Register: \n[lsn] + -- Register: \n[lss] + Set a leading space trap, calling the macro NAME when GNU 'troff' + encounters leading spaces in an input line; the implicit line break + that normally happens in this case is suppressed. If no argument + is supplied, the default leading space behavior is (re-)established + (*note Breaking::). + + The count of leading spaces on an input line is stored in register + 'lsn', and the amount of corresponding horizontal motion in + register 'lss', irrespective of whether a leading space trap is + set. When it is, the leading spaces are removed from the input + line, and no motion is produced before calling NAME. + + +File: groff.info, Node: End-of-input Traps, Prev: Leading Space Traps, Up: Traps + +5.28.5 End-of-input Traps +------------------------- + + -- Request: .em [name] + Set a trap at the end of input, calling macro NAME after the last + line of the last input file has been processed. If no argument is + given, any existing end-of-input trap is removed. + + 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 + \c + . ne 3v + . sp (\\n[.t]u - 3v) + . in +4i + . lc _ + . br + Approved:\t\a + . sp + Date:\t\t\a + .. + . + .em approval + + The '\c' in the above example needs explanation. For historical + reasons (compatibility with AT&T 'troff'), the end-of-input macro + exits as soon as it causes a page break if no partially collected + line remains.(1) (*note End-of-input Traps-Footnote-1::) + + Let us assume that there is no '\c' in the above 'approval' macro, + that the page is full, and last output line has been broken with, + say, a 'br' request. Because there is no more room, a 'ne' request + at this point causes a page ejection, which in turn makes 'troff' + exit immediately as just described. In most situations, this is + not desired; people generally want to format the input after 'ne'. + + To force processing of the whole end-of-input macro independently + of this behavior, it is thus advisable to (invisibly) ensure the + existence of a partially collected line ('\c') whenever there is a + chance that a page break can happen. In the above example, + invoking the 'ne' request ensures that there is room for the + subsequent formatted output on the same page, so we need insert + '\c' only once. + + The next example shows how to append three lines, then start a new + page unconditionally. Since '.ne 1' doesn't give the desired + effect--there is always one line available or we are already at the + beginning of the next page--we temporarily increase the page length + by one line so that we can use '.ne 2'. + + .de EM + .pl +1v + \c + .ne 2 + line one + .br + \c + .ne 2 + line two + .br + \c + .ne 2 + line three + .br + .pl -1v + \c + 'bp + .. + .em EM + + This specific feature affects only the first potential page break + caused by the end-of-input macro; further page breaks emitted by + the macro are handled normally. + + Another possible use of the 'em' request is to make GNU 'troff' + emit a single large page instead of multiple pages. For example, + one may want to produce a long plain text file for reading in a + terminal or emulator without page footers and headers interrupting + the body of the document. One approach is to set the page length + at the beginning of the document to a very large value to hold all + the text,(2) (*note End-of-input Traps-Footnote-2::) and + automatically adjust it to the exact height of the document after + the text has been output. + + .de adjust-page-length + . br + . pl \\n[nl]u \" \n[nl]: current vertical position + .. + . + .de single-page-mode + . pl 99999 + . em adjust-page-length + .. + . + .\" Activate the above code if configured. + .if \n[do-continuous-rendering] \ + . single-page-mode + + Since only one end-of-input trap exists and another macro package + may already use it, care must be taken not to break the mechanism. + A simple solution would be to append the above macro to the macro + package's end-of-input macro using the 'am' request. + + +File: groff.info, Node: End-of-input Traps-Footnotes, Up: End-of-input Traps + + (1) While processing an end-of-input macro, the formatter assumes +that the next page break must be the last; it goes into "sudden death +overtime". + + (2) Another, taken by the 'groff' 'man' macros, is to intercept 'ne' +requests and wrap 'bp' ones. + + +File: groff.info, Node: Diversions, Next: Punning Names, Prev: Traps, Up: GNU troff Reference + +5.29 Diversions +=============== + +In 'roff' systems it is possible to format text as if for output, but +instead of writing it immediately, one can "divert" the formatted text +into a named storage area. It is retrieved later by specifying its name +after a control character. The same name space is used for such +diversions as for strings and macros; see *note Identifiers::. Such +text is sometimes said to be "stored in a macro", but this coinage +obscures the important distinction between macros and strings on one +hand and diversions on the other; the former store _unformatted_ input +text, and the latter capture _formatted_ output. Diversions also do not +interpret arguments. Applications of diversions include "keeps" +(preventing a page break from occurring at an inconvenient place by +forcing a set of output lines to be set as a group), footnotes, tables +of contents, and indices. For orthogonality it is said that GNU 'troff' +is in the "top-level diversion" if no diversion is active (that is, +formatted output is being "diverted" immediately to the output device). + + Dereferencing an undefined diversion will create an empty one of that +name and cause a warning in category 'mac' to be emitted. *Note +Warnings::, for information about the enablement and suppression of +warnings. A diversion does not exist for the purpose of testing with +the 'd' conditional operator until its initial definition ends (*note +Operators in Conditionals::). The following requests are used to create +and alter diversions. + + -- Request: .di [name] + -- Request: .da [name] + Start collecting formatted output in a diversion called NAME. The + 'da' request appends to a diversion called NAME, creating it if + necessary. If NAME already exists as an alias, the target of the + alias is replaced or appended to; recall *note Strings::. The + pending output line is diverted as well. Switching to another + environment (with the 'ev' request) before invoking 'di' or 'da' + avoids including any pending output line in the diversion; see + *note Environments::. + + Invoking 'di' or 'da' without an argument stops diverting output to + the diversion named by the most recent corresponding request. If + 'di' or 'da' is called without an argument when there is no current + diversion, a warning in category 'di' is produced. *Note + Warnings::, for information about the enablement and suppression of + warnings. + + Before the diversion. + .di yyy + In the diversion. + .br + .di + After the diversion. + .br + => After the diversion. + .yyy + => Before the diversion. In the diversion. + + GNU 'troff' supports "box" requests to exclude a partially collected +line from a diversion, as this is often desirable. + + -- Request: .box [name] + -- Request: .boxa [name] + Divert (or append) output to NAME, similarly to the 'di' and 'da' + requests, respectively. Any pending output line is _not_ included + in the diversion. Without an argument, stop diverting output; any + pending output line inside the diversion is discarded. + + Before the box. + .box xxx + In the box. + .br + Hidden treasure. + .box + After the box. + .br + => Before the box. After the box. + .xxx + => In the box. + + Apart from pending output line inclusion and the request names that +populate them, boxes are handled exactly as diversions are. All of the +following 'groff' language elements can be used with them +interchangeably. + + -- Register: \n[.z] + -- Register: \n[.d] + Diversions may be nested. The read-only string-valued register + '.z' contains the name of the current diversion. The read-only + register '.d' contains the current vertical place in the diversion. + If the input text is not being diverted, '.d' reports the same + location as the register 'nl'. + + -- Register: \n[.h] + The read-only register '.h' stores the "high-water mark" on the + current page or in the current diversion. It corresponds to the + text baseline of the lowest line on the page.(1) (*note + Diversions-Footnote-1::) + + .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 implied by the example, vertical motion does not produce text + baselines and thus does not increase the value interpolated by + '\n[.h]'. + + -- Register: \n[dn] + -- Register: \n[dl] + After completing a diversion, the writable registers 'dn' and 'dl' + contain its vertical and horizontal sizes. Only the lines just + processed are counted: for the computation of 'dn' and 'dl', the + requests 'da' and 'boxa' are handled as if 'di' and 'box' had been + used, respectively--lines that have been already stored in the + diversion (box) are not taken into account. + + .\" Center text both horizontally and vertically. + .\" Macro .(c starts centering mode; .)c terminates it. + . + .\" Disable the escape character with .eo so that we + .\" don't have to double backslashes on the "\n"s. + .eo + .de (c + . br + . ev (c + . evc 0 + . in 0 + . nf + . di @c + .. + .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 @c + .. + .ec + + -- Escape sequence: \!anything + -- Escape sequence: \?anything\? + "Transparently" embed ANYTHING into the current diversion, + preventing requests, macro calls, and escape sequences from being + interpreted when read into a diversion. This is useful for + preventing them from taking effect until the diverted text is + actually output. The '\!' escape sequence transparently embeds + input up to and including the end of the line. The '\?' escape + sequence transparently embeds input until its own next occurrence. + + ANYTHING may not contain newlines; use '\!' by itself 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 escape sequences read the data in copy mode. + + If '\!' is used in the top-level diversion, its argument is + directly embedded into GNU 'troff''s intermediate output. This can + be used, for example, to control a postprocessor that processes the + data before it is sent to an output driver. + + The '\?' escape used in the top-level diversion produces no output + at all; its argument is simply ignored. + + -- Request: .output contents + Emit CONTENTS directly to GNU 'troff''s intermediate output + (subject to copy mode interpretation); this is similar to '\!' used + at the top level. An initial neutral double quote in CONTENTS is + stripped to allow embedding of leading spaces. + + This request can't be used before the first page has started--if + you get an error, simply insert '.br' before the 'output' request. + + Use with caution! It is normally only needed for mark-up used by a + postprocessor that does something with the output before sending it + to the output device, filtering out CONTENTS again. + + -- Request: .asciify div + "Unformat" the diversion DIV in a way such that Unicode basic Latin + (ASCII) characters, characters translated with the 'trin' request, + space characters, and some escape sequences, that were formatted + and diverted into DIV are treated like ordinary input characters + when DIV is reread. Doing so can be useful in conjunction with the + 'writem' request. 'asciify' 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 + + 'asciify' cannot return all items in a diversion to their source + equivalent: nodes such as those produced by the '\N' escape + sequence will remain nodes, so the result cannot be guaranteed to + be a pure string. *Note Copy Mode::. Glyph parameters such as the + type face and size are not preserved; use 'unformat' to achieve + that. + + -- Request: .unformat div + Like 'asciify', unformat the diversion DIV. However, 'unformat' + handles only tabs and spaces between words, the latter usually + arising from spaces or newlines in the input. Tabs are treated as + input tokens, and spaces become adjustable again. The vertical + sizes of lines are not preserved, but glyph information (font, type + size, space width, and so on) is retained. + + +File: groff.info, Node: Diversions-Footnotes, Up: Diversions + + (1) Thus, the "water" gets "higher" proceeding _down_ the page. + + +File: groff.info, Node: Punning Names, Next: Environments, Prev: Diversions, Up: GNU troff Reference + +5.30 Punning Names +================== + +Macros, strings, and diversions share a name space; recall *note +Identifiers::. Internally, the same mechanism is used to store them. +You can thus call a macro with string interpolation syntax and vice +versa. + + .de subject + Typesetting + .. + .de predicate + rewards attention to detail + .. + \*[subject] \*[predicate]. + Truly. + => Typesetting + => rewards attention to detail Truly. + +What went wrong? Strings don't contain newlines, but macros do. String +interpolation placed a newline at the end of '\*[subject]', and the next +thing on the input was a space. Then when '\*[predicate]' was +interpolated, it was followed by the empty request '.' on a line by +itself. If we want to use macros as strings, we must take interpolation +behavior into account. + + .de subject + Typesetting\\ + .. + .de predicate + rewards attention to detail\\ + .. + \*[subject] \*[predicate]. + Truly. + => Typesetting rewards attention to detail. Truly. + +By ending each text line of the macros with an escaped '\<RET>', we get +the desired effect (*note Line Continuation::).(1) (*note Punning +Names-Footnote-1::) What would have happened if we had used only one +backslash at a time instead? + + Interpolating a string does not hide existing macro arguments. We +can also place the escaped newline outside the string interpolation +instead of within the string definition. Thus, in a macro, a more +efficient way of doing + + .xx \\$@ + +is + + \\*[xx]\\ + +The latter calling syntax doesn't change the value of '\$0', which is +then inherited from the calling macro (*note Parameters::). + + Diversions can be also called with string syntax. It is sometimes +convenient to copy one-line diversions to a string. + + .di xx + the + .ft I + interpolation system + .ft + .br + .di + .ds yy This is a test of \*(xx\c + \*(yy. + => This is a test of the interpolation system. + +As the previous example shows, it is possible to store formatted output +in strings. The '\c' escape sequence prevents the subsequent newline +from being interpreted as a break (again, *note Line Continuation::). + + Copying multi-output line diversions produces unexpected results. + + .di xxx + a funny + .br + test + .br + .di + .ds yyy This is \*[xxx]\c + \*[yyy]. + => test This is a funny. + + Usually, it is not predictable whether a diversion contains one or +more output lines, so this mechanism should be avoided. With AT&T +'troff', this was the only solution to strip off a final newline from a +diversion. Another disadvantage is that the spaces in the copied string +are already formatted, preventing their adjustment. This can cause ugly +results. + + A clean solution to this problem is available in GNU 'troff', using +the requests 'chop' to remove the final newline of a diversion, and +'unformat' to make the horizontal spaces adjustable again. + + .box xxx + a funny + .br + test + .br + .box + .chop xxx + .unformat xxx + This is \*[xxx]. + => This is a funny test. + + *Note Gtroff Internals::. + + +File: groff.info, Node: Punning Names-Footnotes, Up: Punning Names + + (1) The backslash is doubled. *Note Copy Mode::. + + +File: groff.info, Node: Environments, Next: Suppressing Output, Prev: Diversions, Up: GNU troff Reference + +5.31 Environments +================= + +As discussed in *note Deferring Output::, environments store most of the +parameters that determine the appearance of text. A default environment +named '0' exists when GNU 'troff' starts up; it is modified by +formatting-related requests and escape sequences. + + You can create new environments and switch among them. Only one is +current at any given time. Active environments are managed using a +"stack", a data structure supporting "push" and "pop" operations. The +current environment is at the top of the stack. The same environment +name can be pushed onto the stack multiple times, possibly interleaved +with others. Popping the environment stack does not destroy the current +environment; it remains accessible by name and can be made current again +by pushing it at any time. Environments cannot be renamed or deleted, +and can only be modified when current. To inspect the environment +stack, use the 'pev' request; see *note Debugging::. + + Environments store the following information. + + * a partially collected line, if any + + * data about the most recently output glyph and line (registers + '.cdp', '.cht', '.csk', '.n', '.w') + + * typeface parameters (size, family, style, height and slant, + inter-word and inter-sentence space sizes) + + * page parameters (line length, title length, vertical spacing, line + spacing, indentation, line numbering, centering, right-alignment, + underlining, hyphenation parameters) + + * filling enablement; adjustment enablement and mode + + * tab stops; tab, leader, escape, control, no-break control, + hyphenation, and margin characters + + * input line traps + + * stroke and fill colors + + -- Request: .ev [ident] + -- Register: \n[.ev] + Enter the environment IDENT, which is created if it does not + already exist, using the same parameters as for the default + environment used at startup. With no argument, GNU 'troff' + switches to the previous environment. + + Invoking 'ev' with an argument puts environment IDENT onto the top + of the environment stack. (If it isn't already present in the + stack, this is a proper push.) Without an argument, 'ev' pops the + environment stack, making the previous environment current. It is + an error to pop the environment stack with no previous environment + available. The read-only string-valued register '.ev' contains the + name of the current environment--the one at the top of the stack. + + .ev footnote-env + .fam N + .ps 6 + .vs 8 + .ll -.5i + .ev + + ... + + .ev footnote-env + \[dg] Observe the smaller text and vertical spacing. + .ev + + We can familiarize ourselves with stack behavior by wrapping the + 'ev' request with a macro that reports the contents of the '.ev' + register to the standard error stream. + + .de EV + . ev \\$1 + . tm environment is now \\n[.ev] + .. + . + .EV foo + .EV bar + .EV + .EV baz + .EV + .EV + .EV + + error-> environment is now foo + error-> environment is now bar + error-> environment is now foo + error-> environment is now baz + error-> environment is now foo + error-> environment is now 0 + error-> error: environment stack underflow + error-> environment is now 0 + + -- Request: .evc environment + Copy the contents of ENVIRONMENT to the current environment. + + The following environment data are not copied. + + * a partially collected line, if present; + + * the interruption status of the previous input line (due to use + of the '\c' escape sequence); + + * the count of remaining lines to center, to right-justify, or + to underline (with or without underlined spaces)--these are + set to zero; + + * the activation status of temporary indentation; + + * input line traps and their associated data; + + * the activation status of line numbering (which can be + reactivated with '.nm +0'); and + + * the count 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 + formatted in the environment. + + The '\n[.cht]' register contains the height of the last glyph + formatted in the environment. + + The '\n[.cdp]' register contains the depth of the last glyph + formatted in the 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 GNU 'troff' should place an accent) of + the last glyph formatted in the environment. + + -- Register: \n[.n] + The '\n[.n]' register contains the length of the previous output + line emitted in the environment. + + +File: groff.info, Node: Suppressing Output, Next: Colors, Prev: Environments, Up: GNU troff Reference + +5.32 Suppressing Output +======================= + + -- Escape sequence: \O[num] + Suppress GNU 'troff' output of glyphs and geometric objects. The + sequences '\O2', '\O3', '\O4', and '\O5' are intended for internal + use by 'grohtml'. + + '\O0' + Disable the emission of glyphs and geometric objects to the + output driver, provided that this sequence occurs at the + outermost suppression level (see '\O3' and '\04' below). + Horizontal motions corresponding to non-overstruck glyph + widths still occur. + + '\O1' + Enable the emission of glyphs and geometric objects to the + output driver, provided that this sequence occurs at the + outermost suppression level. + + '\O0' and '\O1' also reset the four registers 'opminx', 'opminy', + 'opmaxx', and 'opmaxy' to -1. These four registers mark the top + left and bottom right hand corners of a box encompassing all + written or drawn output. + + '\O2' + At the outermost suppression level, enable emission of glyphs + and geometric objects, and write to the standard error stream + the page number and values of the four aforementioned + registers encompassing glyphs written since the last + interpolation of a '\O' sequence, as well as the page offset, + line length, image file name (if any), horizontal and vertical + device motion quanta, and input file name. Numeric values are + in basic units. + + '\O3' + Begin a nested suppression level. 'grohtml' uses this + mechanism to create images of output preprocessed with 'gpic', + 'geqn', and 'gtbl'. At startup, GNU 'troff' is at the + outermost suppression level. 'pre-grohtml' generates these + sequences when processing the document, using GNU 'troff' with + the 'ps' output device, Ghostscript, and the PNM tools to + produce images in PNG format. They start a new page if the + device is not 'html' or 'xhtml', to reduce the number of + images crossing a page boundary. + + '\O4' + End a nested suppression level. + + '\O[5PFILE]' + At the outermost suppression level, write the name 'file' to + the standard error stream at position P, which must be one of + 'l', 'r', 'c', or 'i', corresponding to left, right, centered, + and inline alignments within the document, respectively. FILE + is a name associated with the production of the next image. + + -- Register: \n[.O] + Output suppression nesting level applied by '\O3' and '\O4' escape + sequences. + + +File: groff.info, Node: I/O, Next: Postprocessor Access, Prev: Suppressing Output, Up: GNU troff Reference + +5.33 I/O +======== + +'gtroff' has several requests for including files: + + -- Request: .so file + -- Request: .soquiet file + Replace the 'so' request's control line with the contents of the + file named by the argument, "sourcing" it. FILE is sought in the + directories specified by '-I' command-line option. If FILE does + not exist, a warning in category 'file' is produced and the request + has no further effect. *Note Warnings::, for information about the + enablement and suppression of warnings. + + 'so' can be useful for large documents; e.g., allowing each chapter + of a book to be kept in a separate file. However, files + interpolated with 'so' are not preprocessed; to overcome this + limitation, see the 'gsoelim(1)' man page. + + Since GNU 'troff' replaces the entire control line with the + contents of a file, it matters whether 'file' is terminated with a + newline or not. Assume that file 'xxx' contains only the word + 'foo' without a trailing newline. + + $ printf 'foo' > xxx + + The situation is + .so xxx + bar. + => The situation is foobar. + + 'soquiet' works the same way, except that no warning diagnostic is + issued if FILE does not exist. + + -- Request: .pso command + Read the standard output from the specified COMMAND and include it + in place of the 'pso' request. + + It is an error to use this request in safer mode, which is the + default. Invoke GNU 'troff' or a front end with the '-U' option to + enable unsafe mode. + + The comment regarding a final newline for the 'so' request is valid + for 'pso' also. + + -- Request: .mso file + -- Request: .msoquiet file + Identical to the 'so' and 'soquiet' requests, respectively, except + that 'gtroff' searches for the specified FILE in the same + directories as macro files for the '-m' command-line option. If + the file name to be included has the form 'NAME.tmac' and it isn't + found, these requests try 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, 'trf' adds one. Both requests cause a break. + + When used in a diversion, these requests embed a node (*note Gtroff + Internals::) in it that, when reread, causes the contents of FILE + to be transparently copied to the output. In AT&T 'troff', the + contents of FILE are immediately copied 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::). + + For 'cf', within a diversion, "completely unprocessed" means that + each line of a file to be inserted is handled as if it were + preceded by '\!\\!'. + + To define a macro 'x' containing the contents of file 'f', use + + .ev 1 + .di x + .trf f + .di + .ev + + The calls to 'ev' prevent the partially collected output line from + becoming part of the diversion (*note Diversions::). + + -- 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. 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 GNU 'troff' to stop processing. If this were not +there, 'troff' 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. + + It is an error to use this request in safer mode, which is the + default. Invoke GNU 'troff' or a front end with the '-U' option to + enable 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'. + + The intermediate output format of GNU 'troff' 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 anywhere, so it is up to the user to do so. + + It is an error to use this request in safer mode; this is the + default. Give GNU 'troff' or a front end program the '-U' option + to enable unsafe mode. + + 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 + + This works by having the Perl script (run by 'sy') write 'nr' + requests that set the registers 'H', 'M', and 'S' to a temporary + file. The 'roff' document then reads the temporary file using the + 'so' request. + + The registers 'seconds', 'minutes', and 'hours', initialized at + startup of GNU 'troff', should satisfy most requirements. Use the + 'af' request to format their values for output. + + .af hours 00 + .af minutes 00 + .af seconds 00 + \n[hours]:\n[minutes]:\n[seconds] + => 02:17:54 + + The writable register 'systat' 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. + + It is an error to use these requests in safer mode; this is the + default. Give GNU 'troff' or a front end program the '-U' option + to enable 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: an initial neutral double quote in CONTENTS is + stripped to allow embedding of leading spaces, and it is read in + copy 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 sequence: \Ve + -- Escape sequence: \V(ev + -- Escape sequence: \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(3)'. '\V' is interpreted even in copy mode (*note + Copy Mode::). + + +File: groff.info, Node: Postprocessor Access, Next: Miscellaneous, Prev: I/O, Up: GNU troff Reference + +5.34 Postprocessor Access +========================= + +Two escape sequences and two requests enable documents to pass +information directly to a postprocessor. These are useful for +exercising device-specific capabilities that the 'groff' language does +not abstract or generalize; examples include the embedding of hyperlinks +and image files. Device-specific functions are documented in each +output driver's man page, such as 'gropdf(1)', 'grops(1)', or +'grotty(1)'. + + -- Request: .device xxx ... + -- Escape sequence: \X'xxx ...' + Embed all XXX arguments into GNU 'troff' output as parameters to a + device control command 'x X'. The meaning and interpretation of + such parameters is determined by the output driver or other + postprocessor. + + The 'device' request processes its arguments in copy mode (*note + Copy Mode::). An initial neutral double quote in CONTENTS is + stripped to allow embedding of leading spaces. By contrast, within + '\X' arguments, the escape sequences '\&', '\)', '\%', and '\:' are + ignored; '\<SP>' and '\~' are converted to single space characters; + and '\\' has its escape character stripped. So that the basic + Latin subset of the Unicode character set(1) (*note Postprocessor + Access-Footnote-1::) can be reliably encoded in device control + commands, seven special character escape sequences ('\-', '\[aq]', + '\[dq]', '\[ga]', '\[ha]', '\[rs]', and '\[ti]',) are mapped to + basic Latin characters; see the 'groff_char(7)' man page. For this + transformation, character translations and special character + definitions are ignored.(2) (*note Postprocessor + Access-Footnote-2::) The use of any other escape sequence in '\X' + parameters is normally an error. + + If the 'use_charnames_in_special' directive appears in the output + device's 'DESC' file, the use of special character escape sequences + is _not_ an error; they are simply output verbatim (with the + exception of the seven mapped to Unicode basic Latin characters, + discussed above). 'use_charnames_in_special' is currently employed + only by 'grohtml'. + + -- Request: .devicem name + -- Escape sequence: \Yn + -- Escape sequence: \Y(nm + -- Escape sequence: \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 AT&T 'troff' + output format, and confuses drivers that do not know about this + extension (*note Device Control Commands::). + + -- Request: .tag name + -- Request: .taga name + Reserved for internal use. + + +File: groff.info, Node: Postprocessor Access-Footnotes, Up: Postprocessor Access + + (1) that is, ISO 646:1991-IRV or, popularly, "US-ASCII" + + (2) They are bypassed because these parameters are not rendered as +glyphs in the output; instead, they remain abstract characters--in a PDF +bookmark or a URL, for example. + + +File: groff.info, Node: Miscellaneous, Next: Gtroff Internals, Prev: Postprocessor Access, Up: GNU troff Reference + +5.35 Miscellaneous +================== + +We document here GNU 'troff' features that fit poorly elsewhere. + + -- Request: .nm [start [increment [space [indentation]]]] + -- Register: \n[ln] + -- Register: \n[.nm] + Begin (or, with no arguments, cease) numbering output lines. START + assigns the number of the _next_ output line. Only line numbers + divisible by INCREMENT are marked (default: '1'). SPACE configures + the horizontal spacing between the number and the text (default: + '1'). Any given INDENTATION is applied to the numbers (default: + '0'). The third and fourth arguments are reckoned in numeral + widths ('\0'). START must be non-negative and INCREMENT positive. + + The formatter aligns the number to the right in a width of three + numeral spaces plus INDENTATION, then catenates SPACE and the + output line. The line length is _not_ reduced. Depending on the + value of the page offset,(1) (*note Miscellaneous-Footnote-1::) + numbers wider than the allocated space protrude into the left + margin, or shift the output line to the right. + + Line numbering parameters corresponding to missing arguments are + not altered. After numbering is disabled, '.nm +0' resumes it + using the previously active parameters. + + The parameters of 'nm' are associated with the environment (*note + Environments::). + + While numbering is enabled, the output line number register 'ln' is + updated as each line is output, even if no line number is formatted + with it because it is being skipped (it is not a multiple of + INCREMENT) or because numbering is suppressed (see the 'nn' request + below). + + The '.nm' register tracks the enablement status of numbering. + Temporary suspension of numbering with the 'nn' request does _not_ + alter its value. + + .po 5n + .ll 44n + Programming, + when stripped of all its circumstantial irrelevancies, + .nm 999 1 1 -4 + boils down to no more and no less than + .nm +0 3 + very effective thinking so as to avoid unmastered + .nn 2 + complexity, + to very vigorous separation of your many + different concerns. + .br + \(em Edsger Dijkstra + .sp + .nm 1 1 1 + This guy's arrogance takes your breath away. + .br + \(em John Backus + => Programming, when stripped of all its cir- + => 999 cumstantial irrelevancies, boils down to no + => more and no less than very effective think- + => ing so as to avoid unmastered complexity, to + => very vigorous separation of your many dif- + => ferent concerns. + => 1002 -- Edsger Dijkstra + => + => 1 This guy's arrogance takes your breath away. + => 2 -- John Backus + + -- Request: .nn [skip] + -- Register: \n[.nn] + Suppress numbering of the next SKIP output lines that would + otherwise be numbered. The default is 1. 'nn' can be invoked when + line numbering is not active; suppression of numbering will take + effect for SKIP lines once 'nm' enables it. + + The '.nn' register stores the count of output lines still to have + their numbering suppressed. + + This count is associated with the environment (*note + Environments::). + + To test whether the current output line will be numbered, you must +check both the '.nm' and '.nn' registers. + + .de is-numbered + . nop This line + . ie (\\n[.nm] & (1-\\n[.nn])) IS + . el ISN'T + . nop numbered. + . br + .. + Test line numbering. + .is-numbered + .nm 1 + .nn 1 + .is-numbered + .is-numbered + .nm + .is-numbered + => Test line numbering. This line ISN'T numbered. + => This line ISN'T numbered. + => 1 This line IS numbered. + => This line ISN'T numbered. + + -- Request: .mc [margin-character [distance] + Begin (or, with no arguments, cease) writing a "margin-character" + to the right of each output line. The DISTANCE argument separates + MARGIN-CHARACTER from the right margin. If absent, the most recent + value is used; the default is 10 points. If an output line exceeds + the line length, the margin character is appended to it. No margin + character is written on lines produced by the 'tl' request. + + The margin character is a property of the output line; the margin + character last configured when the line is output controls. If the + margin character is disabled before an output line breaks, none is + output (but see below). + + The margin character is associated with the environment (*note + Environments::). + + .ll 5i + .nf + .mc \[br] + This paragraph is marked with a margin character. + .sp + As seen above, vertical space isn't thus marked. + \& + An output line that is present, but empty, is. + => This paragraph is marked with a margin character. | + => + => As seen above, vertical space isn't thus marked. | + => | + => An output line that is present, but empty, is. | + + For compatibility with AT&T 'troff', a call to 'mc' to set the margin +character can't be undone immediately; at least one line gets a margin +character. + + .ll 10n + .nf + .mc | + .mc * + .mc + foo + bar + => foo * + => bar + + The margin character mechanism is commonly used to annotate changes +in documents. The 'groff' distribution ships a program, 'gdiffmk', to +assist with this task.(2) (*note Miscellaneous-Footnote-2::) + + -- Request: .psbb file + -- Register: \n[llx] + -- Register: \n[lly] + -- Register: \n[urx] + -- Register: \n[ury] + Retrieve the bounding box of the PostScript image found in FILE, + which must conform to Adobe's "Document Structuring Conventions" + (DSC), locate a '%%BoundingBox' comment, and store the (upper-, + lower-, -left, -right) values into the registers 'llx', 'lly', + 'urx', and 'ury'. If an error occurs (for example, if no + '%%BoundingBox' comment is present), the formatter sets these + registers to 0. + + The search path for FILE can be controlled with the '-I' + command-line option. + + +File: groff.info, Node: Miscellaneous-Footnotes, Up: Miscellaneous + + (1) Recall *note Line Layout::. + + (2) Historically, tools named 'nrchbar' and 'changebar' were +developed for marking changes with margin characters and could be found +in archives of the 'comp.sources.unix' USENET group. Some proprietary +Unices also offer(ed) a 'diffmk' program. + + +File: groff.info, Node: Gtroff Internals, Next: Debugging, Prev: Miscellaneous, Up: GNU troff Reference + +5.36 '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 that have been passed unprocessed, and a +list of output nodes. Consider the following 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 pending output 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 that isn't adjustable 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. + + 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' that +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'. + + Macro and request arguments preserve compatibility mode enablement. + + .cp 1 \" switch to compatibility mode + .de xx + \\$1 + .. + .cp 0 \" switch compatibility mode off + .xx caf\['e] + => café + +Since compatibility mode is enabled while 'de' is invoked, the macro +'xx' enables compatibility mode when it is called. Argument '$1' can +still be handled properly because it inherits the compatibility mode +enablement status that was active at the point where 'xx' was called. + + After interpolation of the parameters, the compatibility save and +restore tokens are removed. + + +File: groff.info, Node: Gtroff Internals-Footnotes, Up: Gtroff Internals + + (1) Except the escape sequences '\f', '\F', '\H', '\m', '\M', '\R', +'\s', and '\S', which are processed immediately if not in copy mode. + + +File: groff.info, Node: Debugging, Next: Implementation Differences, Prev: Gtroff Internals, Up: GNU troff Reference + +5.37 Debugging +============== + + Standard troff voodoo, just put a power of two backslashes in + front of it until it works and if you still have problems add a \c. + -- Ron Natalie + + GNU 'troff' is not the easiest language to debug, in part thanks to +its design features of recursive interpolation and the use of +multi-stage pipeline processing in the surrounding system. Nevertheless +there exist several features useful for troubleshooting. + + Preprocessors use the 'lf' request to preserve the identity of the +line numbers and names of input files. GNU 'troff' emits a variety of +error diagnostics and supports several categories of warning; the output +of these can be selectively suppressed. A trace of the formatter's +input processing stack can be emitted when errors or warnings occur by +means of GNU 'troff''s '-b' option, or produced on demand with the +'backtrace' request. The 'tm' and related requests can be used to emit +customized diagnostic messages or for instrumentation while +troubleshooting. The 'ex' and 'ab' requests cause early termination +with successful and error exit codes respectively, to halt further +processing when continuing would be fruitless. Examine the state of the +formatter with requests that write lists of defined names (macros, +strings, and diversions), environments, registers, and page location +traps to the standard error stream. + + -- Request: .lf line [file] + Set the input line number (and, optionally, the file name) GNU + 'troff' shall use for error and warning messages. LINE is the + input line number of the _next_ line. Without an argument, the + request is ignored. + + 'lf''s primary purpose is to aid the debugging of documents that + undergo preprocessing. Programs like 'tbl' that transform input in + their own languages into 'roff' requests use it so that any + diagnostic messages emitted by 'troff' correspond to the source + document. + + -- Request: .tm message + -- Request: .tm1 message + -- Request: .tmc message + Send MESSAGE, which consumes the remainder of the input line and + cannot contain special characters, to the standard error stream, + followed by a newline. Leading spaces in MESSAGE are ignored. + + 'tm1' is similar, but recognizes and strips a leading neutral + double quote from MESSAGE to allow the embedding of leading spaces. + + 'tmc' works as 'tm1', but does not append a newline. + + -- Request: .ab [message] + Write any MESSAGE to the standard error stream (like 'tm') and then + abort GNU 'troff'; that is, stop processing and terminate with a + failure status. + + -- Request: .ex + Exit GNU 'troff'; that is, stop processing and terminate with a + successful status. To stop processing only the current file, use + the 'nx' request; see *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 such statements, use the '-r' option to set the register. + + groff -rDB=1 file + + If it is known in advance that there are many errors and no useful +output, GNU 'troff' can be forced to suppress formatted output with the +'-z' option. + + -- Request: .pev + Report the state of the current environment followed by that of all + other environments to the standard error stream. + + -- Request: .pm + Report, to the standard error stream, the names of all defined + macros, strings, and diversions with their sizes in bytes. + + -- Request: .pnr + Report the names and contents of all currently defined registers to + the standard error stream. + + -- Request: .ptr + Report the names and positions of all page location traps to the + standard error stream. Empty slots in the list, where a trap has + been planted but subsequently (re)moved, are printed as well. + + -- 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 + Write the state of the input stack to the standard error stream. + + Consider the following in a file 'test'. + + .de xxx + . backtrace + .. + .de yyy + . xxx + .. + . + .yyy + error-> troff: backtrace: 'test':2: macro 'xxx' + error-> troff: backtrace: 'test':5: macro 'yyy' + error-> troff: backtrace: file 'test':8 + + The '-b' option of GNU 'troff' causes a backtrace to be generated + on each error or warning. Some warnings have to be enabled; *Note + Warnings::. + + -- Register: \n[slimit] + If greater than 0, sets the maximum quantity of objects on GNU + 'troff''s internal input stack. If less than or equal to 0, there + is no limit: recursion can continue until program memory is + exhausted. The default is 1,000. + + -- Request: .warnscale su + Set the scaling unit used in certain warnings to SU, which can take + the values 'u', 'i', 'c', 'p', and 'P'. The default is 'i'. + + -- Request: .spreadwarn [limit] + Emit a 'break' warning if the additional space inserted for each + space between words in an output line adjusted to both margins with + '.ad b' is larger than or equal to LIMIT. A negative value is + treated as zero; an absent argument toggles the warning on and off + without changing LIMIT. The default scaling unit is 'm'. At + startup, 'spreadwarn' is inactive and LIMIT is 3m. + + For example, + + .spreadwarn 0.2m + + causes a warning if 'break' warnings are not suppressed and + 'gtroff' must add 0.2m or more for each inter-word space in a line. + *Note Warnings::. + + GNU 'troff' has command-line options for reporting warnings ('-w') +and backtraces ('-b') when a warning or an error occurs. + + -- Request: .warn [n] + -- Register: \n[.warn] + Select the categories, or "types", of reported warnings. N is the + sum of the numeric codes associated with each warning category that + is to be enabled; all other categories are disabled. The + categories and their associated codes are listed in *note + Warnings::. For example, '.warn 0' disables all warnings, and + '.warn 1' disables all warnings except those about missing glyphs. + If no argument is given, all warning categories are enabled. + + The read-only register '.warn' contains the sum of the numeric + codes of enabled warning categories. + +* Menu: + +* Warnings:: + + +File: groff.info, Node: Warnings, Prev: Debugging, Up: Debugging + +5.37.1 Warnings +--------------- + +Warning diagnostics emitted by GNU 'troff' are divided into named, +numbered categories. The name associated with each warning category is +used by the '-w' and '-W' options. Each category is also assigned a +power of two; the sum of enabled category values is used by the 'warn' +request and the '.warn' register. + + Warnings of each category are produced under the following +circumstances. + +'char' +'1' + No mounted font defines a glyph for the requested character. This + category is enabled by default. + +'number' +'2' + An invalid numeric expression was encountered. This category is + enabled by default. *Note Numeric Expressions::. + +'break' +'4' + A filled output line could not be broken such that its length was + less than the output line length '\n[.l]'. This category is + enabled by default. + +'delim' +'8' + The closing delimiter in an escape sequence was missing or + mismatched. + +'el' +'16' + The 'el' request was encountered with no prior corresponding 'ie' + request. *Note if-else::. + +'scale' +'32' + A scaling unit inappropriate to its context was used in a numeric + expression. + +'range' +'64' + A numeric expression was out of range for its context. + +'syntax' +'128' + A self-contradictory hyphenation mode was requested; an empty or + incomplete numeric expression was encountered; an operand to a + numeric operator was missing; an attempt was made to define a + recursive, empty, or nonsensical character class; or a 'groff' + extension conditional expression operator was used while in + compatibility mode. + +'di' +'256' + A 'di', 'da', 'box', or 'boxa' request was invoked without an + argument when there was no current diversion. + +'mac' +'512' + An undefined string, macro, or diversion was used. When such an + object is dereferenced, an empty one of that name is automatically + created. So, unless it is later deleted, at most one warning is + given for each. + + This warning is also emitted upon an attempt to move an unplanted + trap macro (*note Page Location Traps::). In such cases, the + unplanted macro is _not_ dereferenced, so it is not created if it + does not exist. + +'reg' +'1024' + An undefined register was used. When an undefined register is + dereferenced, it is automatically defined with a value of 0. So, + unless it is later deleted, at most one warning is given for each. + +'tab' +'2048' + A tab character was encountered where a number was expected, or + appeared in an unquoted macro argument. + +'right-brace' +'4096' + A right brace escape sequence '\}' was encountered where a number + was expected. + +'missing' +'8192' + A request was invoked with a mandatory argument absent. + +'input' +'16384' + An invalid character occurred on the input stream. + +'escape' +'32768' + An unsupported escape sequence was encountered. + +'space' +'65536' + A space was missing between a request or macro and its argument. + This warning is produced when an undefined name longer than two + characters is encountered and the first two characters of the name + constitute a defined name. No request is invoked, no macro called, + and an empty macro is not defined. This category is enabled by + default. It never occurs in compatibility mode. + +'font' +'131072' + A non-existent font was selected, or the selection was ignored + because a font selection escape sequence was used after the output + line continuation escape sequence on an input line. This category + is enabled by default. + +'ig' +'262144' + An invalid escape sequence occurred in input ignored using the 'ig' + request. This warning category diagnoses a condition that is an + error when it occurs in non-ignored input. + +'color' +'524288' + An undefined color was selected, an attempt was made to define a + color using an unrecognized color space, an invalid component in a + color definition was encountered, or an attempt was made to + redefine a default color. + +'file' +'1048576' + An attempt was made to load a file that does not exist. This + category is enabled by default. + + Two warning names group other warning categories for convenience. + +'all' + All warning categories except 'di', 'mac' and 'reg'. This + shorthand is intended to produce all warnings that are useful with + macro packages written for AT&T 'troff' and its descendants, which + have less fastidious diagnostics than GNU 'troff'. + +'w' + All warning categories. Authors of documents and macro packages + targeting 'groff' are encouraged to use this setting. + + +File: groff.info, Node: Implementation Differences, Next: Safer Mode, Prev: Debugging, Up: GNU troff Reference + +5.38 Implementation Differences +=============================== + +GNU 'troff' has a number of features that cause incompatibilities with +documents written for other versions of 'troff'. Some GNU extensions to +'troff' have become supported by other implementations. + +* Menu: + +* Safer Mode:: +* Compatibility Mode:: +* Other Differences:: + + +File: groff.info, Node: Safer Mode, Next: Compatibility Mode, Prev: Implementation Differences, Up: Implementation Differences + +5.38.1 Safer Mode +----------------- + +The formatter operates in "safer" mode by default; to mitigate risks +from untrusted input documents, the 'pi' and 'sy' requests are disabled. +GNU 'troff''s '-U' option enables "unsafe mode", restoring their +function and enabling additional 'groff' extension requests, 'open', +'opena', and 'pso'. *Note I/O::. + + +File: groff.info, Node: Compatibility Mode, Next: Safer Mode, Prev: Other Differences, Up: Implementation Differences + +5.38.2 Compatibility Mode +------------------------- + +Long identifier names may be GNU 'troff''s most obvious innovation. +AT&T 'troff' interprets '.dsabcd' as defining a string 'ab' with +contents 'cd'. Normally, GNU 'troff' interprets this as a call of a +macro named 'dsabcd'. AT&T 'troff' also interprets '\*[' and '\n[' as +an interpolation of a string or register, respectively, named '['. In +GNU 'troff', however, the '[' is normally interpreted as delimiting a +long name. In compatibility mode, GNU 'troff' interprets names in the +traditional way; they thus can be two characters long at most. + + -- Request: .cp [n] + -- Register: \n[.C] + If N is missing or non-zero, turn on compatibility mode; otherwise, + turn it off. + + The read-only register '.C' is 1 if compatibility mode is on, + 0 otherwise. + + Compatibility mode can be also turned on with the '-C' command-line + option. + + -- Request: .do name + -- Register: \n[.cp] + The 'do' request interprets the string, request, diversion, or + macro NAME (along with any further arguments) with compatibility + mode disabled. Compatibility mode is restored (only if it was + active) when the _expansion_ of NAME is interpreted; that is, the + restored compatibility state applies to the contents of the macro, + string, or diversion NAME as well as data read from files or pipes + if NAME is any of the 'so', 'soquiet', 'mso', 'msoquiet', or 'pso' + requests. + + The following example illustrates several aspects of 'do' behavior. + + .de mac1 + FOO + .. + .de1 mac2 + groff + .mac1 + .. + .de mac3 + compatibility + .mac1 + .. + .de ma + \\$1 + .. + .cp 1 + .do mac1 + .do mac2 \" mac2, defined with .de1, calls "mac1" + .do mac3 \" mac3 calls "ma" with argument "c1" + .do mac3 \[ti] \" groff syntax accepted in .do arguments + => FOO groff FOO compatibility c1 ~ + + The read-only register '.cp', meaningful only when dereferenced + from a 'do' request, is 1 if compatibility mode was on when the + 'do' request was encountered, and 0 if it was not. This register + is specialized and may require a statement of rationale. + + When writing macro packages or documents that use GNU 'troff' + features and which may be mixed with other packages or documents + that do not--common scenarios include serial processing of man + pages or use of the 'so' or 'mso' requests--you may desire correct + operation regardless of compatibility mode enablement in the + surrounding context. It may occur to you to save the existing + value of '\n(.C' into a register, say, '_C', at the beginning of + your file, turn compatibility mode off with '.cp 0', then restore + it from that register at the end with '.cp \n(_C'. At the same + time, a modular design of a document or macro package may lead you + to multiple layers of inclusion. You cannot use the same register + name everywhere lest you "clobber" the value from a preceding or + enclosing context. The two-character register name space of AT&T + 'troff' is confining and mnemonically challenging; you may wish to + use the more capacious name space of GNU 'troff'. However, + attempting '.nr _my_saved_C \n(.C' will not work in compatibility + mode; the register name is too long. "This is exactly what 'do' is + for," you think, '.do nr _my_saved_C \n(.C'. The foregoing will + always save zero to your register, because 'do' turns compatibility + mode _off_ while it interprets its argument list. + + To robustly save compatibility mode before switching it off, use + + .do nr _my_saved_C \n[.cp] + .cp 0 + + at the beginning of your file, followed by + + .cp \n[_my_saved_C] + .do rr _my_saved_C + + at the end. As in the C language, we all have to share one big + name space, so choose a register name that is unlikely to collide + with other uses. + + Normally, GNU 'troff' preserves the interpolation depth in delimited +arguments, but not in compatibility mode. + + .ds xx ' + \w'abc\*(xxdef' + => 168 (normal mode on a terminal device) + => 72def' (compatibility mode on a terminal device) + + Furthermore, the escape sequences '\f', '\H', '\m', '\M', '\R', '\s', +and '\S' are transparent for the purpose of recognizing a control +character at the beginning of a line only in compatibility mode. For +example, this code produces bold output in both cases, but the text +differs. + + .de xx + Hello! + .. + \fB.xx\fP + => .xx (normal mode) + => Hello! (compatibility mode) + + Normally, the syntax form '\s'N accepts only a single character (a +digit) for N, consistently with other forms that originated in AT&T +'troff', like '\*', '\$', '\f', '\g', '\k', '\n', and '\z'. In +compatibility mode only, a non-zero N must be in the range 4-39. Legacy +documents relying upon this quirk of parsing(1) (*note Compatibility +Mode-Footnote-1::) should be migrated to another '\s' form. + + +File: groff.info, Node: Compatibility Mode-Footnotes, Up: Compatibility Mode + + (1) The Graphic Systems C/A/T phototypesetter (the original device +target for AT&T 'troff') supported only a few discrete type sizes in the +range 6-36 points, so Ossanna contrived a special case in the parser to +do what the user must have meant. Kernighan warned of this in the 1992 +revision of CSTR #54 (§2.3), and more recently, McIlroy referred to it +as a "living fossil". + + +File: groff.info, Node: Other Differences, Prev: Compatibility Mode, Up: Implementation Differences + +5.38.3 Other Differences +------------------------ + +'groff' request names unrecognized by other 'troff' implementations will +likely be ignored by them; escape sequences that are 'groff' extensions +are liable to be interpreted as if the escape character were not +present. For example, the adjustable, non-breaking escape sequence '\~' +is also supported by Heirloom Doctools 'troff' 050915 (September 2005), +'mandoc' 1.9.5 (2009-09-21), 'neatroff' (commit 1c6ab0f6e, 2016-09-13), +and Plan 9 from User Space 'troff' (commit 93f8143600, 2022-08-12), but +not by Solaris or Documenter's Workbench 'troff's. *Note Manipulating +Filling and Adjustment::. + + GNU 'troff' does not allow the use of the escape sequences '\|', +'\^', '\&', '\{', '\}', '\<SP>', '\'', '\`', '\-', '\_', '\!', '\%', and +'\c' in identifiers; AT&T 'troff' does. The '\A' escape sequence (*note +Identifiers::) may be helpful in avoiding use of these escape sequences +in names. + + When adjusting to both margins, AT&T 'troff' at first adjusts spaces +starting from the right; GNU 'troff' begins from the left. Both +implementations adjust spaces from opposite ends on alternating output +lines in this adjustment mode to prevent "rivers" in the text. + + GNU 'troff' does not always hyphenate words as AT&T 'troff' does. +The AT&T implementation uses a set of hard-coded rules specific to +English, while GNU 'troff' uses language-specific hyphenation pattern +files derived from TeX. Furthermore, in old versions of 'troff' there +was a limited amount of space to store hyphenation exceptions (arguments +to the 'hw' request); GNU 'troff' has no such restriction. + + GNU 'troff' predefines a string '.T' containing the argument given to +the '-T' command-line option, namely the current output device (for +example, 'pdf' or 'utf8'). The existence of this string is a common +feature of post-CSTR #54 'troff's(1) (*note Other +Differences-Footnote-1::) but valid values are specific to each +implementation. + + AT&T 'troff' ignored attempts to remove read-only registers; GNU +'troff' honors such requests. *Note Built-in Registers::. + + The (read-only) register '.T' interpolates 1 if GNU 'troff' is called +with the '-T' command-line option, and 0 otherwise. This behavior +differs from AT&T 'troff', which interpolated 1 only if 'nroff' was the +formatter and was called with '-T'. + + AT&T 'troff' and other implementations handle the 'lf' request +differently. For them, its LINE argument changes the line number of the +_current_ line. + + AT&T 'troff' had only environments named '0', '1', and '2'. In GNU +'troff', any number of environments may exist, using any valid +identifiers for their names (*note Identifiers::.) + + Fractional type sizes cause one noteworthy incompatibility. In AT&T +'troff' the 'ps' request ignores scaling units and thus '.ps 10u' sets +the type size to 10 points, whereas in GNU 'troff' it sets the type size +to 10 _scaled_ points. *Note Using Fractional Type Sizes::. + + The 'ab' request differs from AT&T 'troff': GNU 'troff' writes no +message to the standard error stream if no arguments are given, and it +exits with a failure status instead of a successful one. + + The 'bp' request differs from AT&T 'troff': GNU 'troff' does not +accept a scaling unit on the argument, a page number; the former +(somewhat uselessly) does. + + The 'pm' request differs from AT&T 'troff': GNU 'troff' reports the +sizes of macros, strings, and diversions in bytes and ignores an +argument to report only the sum of the sizes. + + Unlike AT&T 'troff', GNU 'troff' does not ignore the 'ss' request if +the output is a terminal device; instead, the values of minimal +inter-word and additional inter-sentence space are each rounded down to +the nearest multiple of 12. + + In GNU 'troff' there is a fundamental difference between +(unformatted) characters and (formatted) 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 characters immediately +before the glyph is added to an output line. Macros, diversions, and +strings are all, in fact, the same type of object; they contain a +sequence of intermixed character and glyph nodes. Special characters +transform from one to the other: before being added to the output, they +behave as characters; afterward, they are glyphs. A glyph node does not +behave like a character node when it is processed by a macro: it does +not inherit any of the special properties that the character from which +it was constructed might have had. For example, the input + + .di x + \\\\ + .br + .di + .x + +produces '\\' in GNU 'troff'. Each pair of backslashes becomes one +backslash _glyph_; the resulting backslashes are thus not interpreted as +escape _characters_ when they are reread as the diversion is output. +AT&T 'troff' _would_ interpret them as escape characters when rereading +them and end up printing one '\'. + + One correct way to obtain a printable backslash in most documents is +to use the '\e' escape sequence; this always prints a single instance of +the current escape character,(2) (*note Other Differences-Footnote-2::) +regardless of whether or not it is used in a diversion; it also works in +both GNU 'troff' and AT&T 'troff'. + + The other correct way, appropriate in contexts independent of the +backslash's common use as a 'troff' escape character--perhaps in +discussion of character sets or other programming languages--is the +character escape '\(rs' or '\[rs]', for "reverse solidus", from its name +in the ECMA-6 (ISO/IEC 646) standard.(3) (*note Other +Differences-Footnote-3::) + + To store an escape sequence in a diversion that is 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::. + + In the somewhat pathological case where a diversion exists containing +a partially collected line and a partially collected line at the +top-level diversion has never existed, AT&T 'troff' will output the +partially collected line at the end of input; GNU 'troff' will not. + + +File: groff.info, Node: Other Differences-Footnotes, Up: Other Differences + + (1) DWB 3.3, Solaris, Heirloom Doctools, and Plan 9 'troff' all +support it. + + (2) Naturally, if you've changed the escape character, you need to +prefix the 'e' with whatever it is--and you'll likely get something +other than a backslash in the output. + + (3) The 'rs' special character identifier was not defined in AT&T +'troff''s font description files, but is in those of its lineal +descendant, Heirloom Doctools 'troff', as of the latter's 060716 release +(July 2006). + + +File: groff.info, Node: File Formats, Next: Copying This Manual, Prev: GNU troff Reference, Up: Top + +6 File Formats +************** + +All files read and written by 'gtroff' are text files. The following +two sections describe their format. + +* Menu: + +* gtroff Output:: +* Device and Font Description Files:: + + +File: groff.info, Node: gtroff Output, Next: Device and Font Description Files, Prev: File Formats, Up: File Formats + +6.1 'gtroff' Output +=================== + +This section describes the 'groff' intermediate output format produced +by GNU 'troff'. + + As 'groff' is a wrapper program around GNU 'troff' and automatically +calls an output driver (or "postprocessor"), this output does not show +up normally. This is why it is called _intermediate_. 'groff' provides +the option '-Z' to inhibit postprocessing such that the produced +intermediate output is sent to standard output just as it is when +calling GNU 'troff' directly. + + Here, the term "troff output" describes what is output by GNU +'troff', while "intermediate output" refers to the language that is +accepted by the parser that prepares this output for the output drivers. +This parser handles whitespace more flexibly than AT&T's implementation +and implements obsolete elements for compatibility; otherwise, both +formats are the same.(1) (*note gtroff Output-Footnote-1::) + + The main purpose of the intermediate output concept is to facilitate +the development of postprocessors by providing a common programming +interface for all devices. It has a language of its own that is +completely different from the 'gtroff' language. While the 'gtroff' +language is a high-level programming language for text processing, the +intermediate output language is a kind of low-level assembler language +by specifying all positions on the page for writing and drawing. + + The intermediate output produced by 'gtroff' is fairly readable, +while output from AT&T 'troff' is rather hard to understand because of +strange habits that are still supported, but not used any longer by +'gtroff'. + +* Menu: + +* Language Concepts:: +* Command Reference:: +* Intermediate Output Examples:: +* Output Language Compatibility:: + + +File: groff.info, Node: gtroff Output-Footnotes, Up: gtroff Output + + (1) The parser and postprocessor for intermediate output can be found +in the file +'GROFF-SOURCE-DIR/src/libs/libdriver/input.cpp'. + + +File: groff.info, Node: Language Concepts, Next: Command Reference, Prev: gtroff Output, Up: gtroff Output + +6.1.1 Language Concepts +----------------------- + +The fundamental operation of the GNU 'troff' formatter is the +translation of the 'groff' input language into a device-independent form +primarily concerned with what has to be written or drawn at specific +positions on the output device. This language is simple and imperative. +In the following discussion, the term "command" always refers to this +intermediate output language, and never to the 'groff' language intended +for direct use by document authors. Intermediate output commands +comprise several categories: glyph output; font, color, and text size +selection; motion of the printing position; page advancement; drawing of +geometric objects; and device control commands, a catch-all for +operations not easily classified as any of the foregoing, such as +directives to start and stop output, identify the intended output +device, or place URL hyperlinks in supported output formats. + +* Menu: + +* Separation:: +* Argument Units:: +* Document Parts:: + + +File: groff.info, Node: Separation, Next: Argument Units, Prev: Language Concepts, Up: Language Concepts + +6.1.1.1 Separation +.................. + +AT&T 'troff' output has strange requirements regarding whitespace. The +'gtroff' output parser, however, is more tolerant, making whitespace +maximally optional. Such characters, i.e., the tab, space, and newline, +always have a syntactical meaning. They are never printable because +spacing within the output is always done by positioning commands. + + Any sequence of space or tab characters is treated as a single +"syntactical space". It separates commands and arguments, but is only +required when there would occur a clashing between the command code and +the arguments without the space. Most often, this happens when +variable-length command names, arguments, argument lists, or command +clusters meet. Commands and arguments with a known, fixed length need +not be separated by syntactical space. + + A line break is a syntactical element, too. Every command argument +can be followed by whitespace, a comment, or a newline character. Thus +a "syntactical line break" is defined to consist of optional syntactical +space that is optionally followed by a comment, and a newline character. + + The normal commands, those for positioning and text, consist of a +single letter taking a fixed number of arguments. For historical +reasons, the parser allows stacking of such commands on the same line, +but fortunately, in 'gtroff''s intermediate output, every command with +at least one argument is followed by a line break, thus providing +excellent readability. + + The other commands--those for drawing and device controlling--have a +more complicated structure; some recognize long command names, and some +take a variable number of arguments. So all 'D' and 'x' commands were +designed to request a syntactical line break after their last argument. +Only one command, 'x X', has an argument that can span several input +lines; all other commands must have all of their arguments on the same +line as the command, i.e., the arguments may not be split by a line +break. + + Empty lines (these are lines containing only space and/or a comment), +can occur everywhere. They are just ignored. + + +File: groff.info, Node: Argument Units, Next: Document Parts, Prev: Separation, Up: Language Concepts + +6.1.1.2 Argument Units +...................... + +Some commands take integer arguments that are assumed to represent +values in a measurement unit, but the letter for the corresponding +scaling unit is not written with the output command arguments. Most +commands assume the scaling unit 'u', the basic unit of the device, some +use 'z', the scaled point unit of the device, while others, such as the +color commands, expect plain integers. + + Single characters can have the eighth bit set, as can the names of +fonts and special characters. The names of characters and fonts can be +of arbitrary length. A character that is to be printed is always in the +current font. + + A string argument is always terminated by the next whitespace +character (space, tab, or newline); an embedded '#' character is +regarded as part of the argument, not as the beginning of a comment +command. An integer argument is already terminated by the next +non-digit character, which then is regarded as the first character of +the next argument or command. + + +File: groff.info, Node: Document Parts, Prev: Argument Units, Up: Language Concepts + +6.1.1.3 Document Parts +...................... + +A correct intermediate output document consists of two parts, the +"prologue" and the "body". + + The task of the prologue is to set the general device parameters +using three exactly specified commands. 'gtroff''s prologue is +guaranteed to consist of the following three lines (in that order): + + x T DEVICE + x res N H V + x init + +with the arguments set as outlined in *note Device Control Commands::. +The parser for the intermediate output format is able to interpret +additional whitespace and comments as well even in the prologue. + + The body is the main section for processing the document data. +Syntactically, it is a sequence of any commands different from the ones +used in the prologue. Processing is terminated as soon as the first +'x stop' command is encountered; the last line of any 'gtroff' +intermediate output always contains such a command. + + Semantically, the body is page oriented. A new page is started by a +'p' command. Positioning, writing, and drawing commands are always done +within the current page, so they cannot occur before the first 'p' +command. Absolute positioning (by the 'H' and 'V' commands) is done +relative to the current page; all other positioning is done relative to +the current location within this page. + + +File: groff.info, Node: Command Reference, Next: Intermediate Output Examples, Prev: Language Concepts, Up: gtroff Output + +6.1.2 Command Reference +----------------------- + +This section describes all intermediate output commands, both from AT&T +'troff' as well as the 'gtroff' extensions. + +* Menu: + +* Comment Command:: +* Simple Commands:: +* Graphics Commands:: +* Device Control Commands:: +* Obsolete Command:: + + +File: groff.info, Node: Comment Command, Next: Simple Commands, Prev: Command Reference, Up: Command Reference + +6.1.2.1 Comment Command +....................... + +'#ANYTHING<end of line>' + A comment. Ignore any characters from the '#' character up to the + next newline character. + + This command is the only possibility for commenting in the + intermediate output. Each comment can be preceded by arbitrary + syntactical space; every command can be terminated by a comment. + + +File: groff.info, Node: Simple Commands, Next: Graphics Commands, Prev: Comment Command, Up: Command Reference + +6.1.2.2 Simple Commands +....................... + +The commands in this subsection have a command code consisting of a +single character, taking a fixed number of arguments. Most of them are +commands for positioning and text writing. These commands are tolerant +of whitespace. Optionally, syntactical space can be inserted before, +after, and between the command letter and its arguments. All of these +commands are stackable; i.e., they can be preceded by other simple +commands or followed by arbitrary other commands on the same line. A +separating syntactical space is necessary only when two integer +arguments would clash or if the preceding argument ends with a string +argument. + +'C ID<whitespace>' + Typeset the glyph of the special character ID. Trailing + syntactical space is necessary to allow special character names of + arbitrary length. The drawing position is not advanced. + +'c G' + Typeset the glyph of the ordinary character C. The drawing + position is not advanced. + +'f N' + Select the font mounted at position N. N cannot be negative. + +'H N' + Horizontally move the drawing position to N basic units from the + left edge of the page. N cannot be negative. + +'h N' + Move the drawing position right N basic units. AT&T 'troff' + allowed negative N; GNU 'troff' does not produce such values, but + 'groff''s output driver library handles them. + +'m COLOR-SCHEME [COMPONENT ...]' + Select the stroke color using the COMPONENTs in the color space + SCHEME. Each COMPONENT is an integer between 0 and 65535. The + quantity of components and their meanings vary with each SCHEME. + This command is a 'groff' extension. + + 'mc CYAN MAGENTA YELLOW' + Use the CMY color scheme with components cyan, magenta, and + yellow. + + 'md' + Use the default color (no components; black in most cases). + + 'mg GRAY' + Use a grayscale color scheme with a component ranging between + 0 (black) and 65535 (white). + + 'mk CYAN MAGENTA YELLOW BLACK' + Use the CMYK color scheme with components cyan, magenta, + yellow, and black. + + 'mr RED GREEN BLUE' + Use the RGB color scheme with components red, green, and blue. + +'N N' + Typeset the glyph with index N in the current font. N is normally + a non-negative integer. The drawing position is not advanced. The + 'html' and 'xhtml' devices use this command with negative N to + produce unbreakable space; the absolute value of N is taken and + interpreted in basic units. + +'n B A' + Indicate a break. No action is performed; the command is present + to make the output more easily parsed. The integers B and A + describe the vertical space amounts before and after the break, + respectively. GNU 'troff' issues this command but 'groff''s output + driver library ignores it. See 'v' and 'V' below. + +'p N' + Begin a new page, setting its number to N. Each page is + independent, even from those using the same number. The vertical + drawing position is set to 0. All positioning, writing, and + drawing commands are interpreted in the context of a page, so a + 'p' command must precede them. + +'s N' + Set type size to N scaled points (unit 'z' in GNU 'troff'. AT&T + 'troff' used unscaled points 'p' instead; see *note Output Language + Compatibility::. + +'t XYZ<whitespace>' +'t XYZ DUMMY-ARG<whitespace>' + Typeset a word XYZ; that is, set a sequence of ordinary glyphs + named X, Y, Z, ..., terminated by a space character or a line + break; an optional second integer argument is ignored (this allows + the formatter to generate an even number of arguments). Each glyph + is set at the current drawing position, and the position is then + advanced horizontally by the glyph's width. A glyph's width is + read from its metrics in the font description file, scaled to the + current type size, and rounded to a multiple of the horizontal + motion quantum. Use the 'C' command to emplace glyphs of special + characters. The 't' command is a 'groff' extension and is output + only for devices whose 'DESC' file contains the 'tcommand' + directive; see *note DESC File Format::. + +'u N XYZ<whitespace>' + Typeset word XYZ with track kerning. As 't', but after placing + each glyph, the drawing position is further advanced horizontally + by N basic units ('u'). The 'u' command is a 'groff' extension and + is output only for devices whose 'DESC' file contains the + 'tcommand' directive; see *note DESC File Format::. + +'V N' + Vertically move the drawing position to N basic units from the top + edge of the page. N cannot be negative. + +'v N' + Move the drawing position down N basic units. AT&T 'troff' allowed + negative N; GNU 'troff' does not produce such values, but 'groff''s + output driver library handles them. + +'w' + Indicate an inter-word space. No action is performed; the command + is present to make the output more easily parsed. Only adjustable, + breakable inter-word spaces are thus described; those resulting + from '\~' or horizontal motion escape sequences are not. GNU + 'troff' issues this command but 'groff''s output driver library + ignores it. See 'h' and 'H' above. + + +File: groff.info, Node: Graphics Commands, Next: Device Control Commands, Prev: Simple Commands, Up: Command Reference + +6.1.2.3 Graphics Commands +......................... + +Each graphics or drawing command in the intermediate output starts with +the letter 'D', followed by one or two characters that specify a +subcommand; this is followed by a fixed or variable number of integer +arguments that are separated by a single space character. A 'D' command +may not be followed by another command on the same line (apart from a +comment), so each 'D' command is terminated by a syntactical line break. + + 'gtroff' output follows the classical spacing rules (no space between +command and subcommand, all arguments are preceded by a single space +character), but the parser allows optional space between the command +letters and makes the space before the first argument optional. As +usual, each space can be any sequence of tab and space characters. + + Some graphics commands can take a variable number of arguments. In +this case, they are integers representing a size measured in basic units +'u'. The arguments called H1, H2, ..., HN stand for horizontal +distances where positive means right, negative left. The arguments +called V1, V2, ..., VN stand for vertical distances where positive means +down, negative up. All these distances are offsets relative to the +current location. + + Each graphics command directly corresponds to a similar 'gtroff' '\D' +escape sequence. *Note Drawing Geometric Objects::. + + Unknown 'D' commands are assumed to be device-specific. Its +arguments are parsed as strings; the whole information is then sent to +the postprocessor. + + In the following command reference, the syntax element <line break> +means a syntactical line break as defined above. + +'D~ H1 V1 H2 V2 ... HN VN<line break>' + Draw B-spline from current position to offset (H1,V1), then to + offset (H2,V2), if given, etc., up to (HN,VN). This command takes + a variable number of argument pairs; the current position is moved + to the terminal point of the drawn curve. + +'Da H1 V1 H2 V2<line break>' + Draw arc from current position to (H1,V1)+(H2,V2) with center at + (H1,V1); then move the current position to the final point of the + arc. + +'DC D<line break>' +'DC D DUMMY-ARG<line break>' + Draw a solid circle using the current fill color with diameter D + (integer in basic units 'u') with leftmost point at the current + position; then move the current position to the rightmost point of + the circle. An optional second integer argument is ignored (this + allows the formatter to generate an even number of arguments). + This command is a 'gtroff' extension. + +'Dc D<line break>' + Draw circle line with diameter D (integer in basic units 'u') with + leftmost point at the current position; then move the current + position to the rightmost point of the circle. + +'DE H V<line break>' + Draw a solid ellipse in the current fill color with a horizontal + diameter of H and a vertical diameter of V (both integers in basic + units 'u') with the leftmost point at the current position; then + move to the rightmost point of the ellipse. This command is a + 'gtroff' extension. + +'De H V<line break>' + Draw an outlined ellipse with a horizontal diameter of H and a + vertical diameter of V (both integers in basic units 'u') with the + leftmost point at current position; then move to the rightmost + point of the ellipse. + +'DF COLOR-SCHEME [COMPONENT ...]<line break>' + Set fill color for solid drawing objects using different color + schemes; the analogous command for setting the color of text, line + graphics, and the outline of graphic objects is 'm'. The color + components are specified as integer arguments between 0 and 65535. + The number of color components and their meaning vary for the + different color schemes. These commands are generated by + 'gtroff''s escape sequences '\D'F ...'' and '\M' (with no other + corresponding graphics commands). No position changing. This + command is a 'gtroff' extension. + + 'DFc CYAN MAGENTA YELLOW<line break>' + Set fill color for solid drawing objects using the CMY color + scheme, having the 3 color components CYAN, MAGENTA, and + YELLOW. + + 'DFd<line break>' + Set fill color for solid drawing objects to the default fill + color value (black in most cases). No component arguments. + + 'DFg GRAY<line break>' + Set fill color for solid drawing objects to the shade of gray + given by the argument, an integer between 0 (black) and 65535 + (white). + + 'DFk CYAN MAGENTA YELLOW BLACK<line break>' + Set fill color for solid drawing objects using the CMYK color + scheme, having the 4 color components CYAN, MAGENTA, YELLOW, + and BLACK. + + 'DFr RED GREEN BLUE<line break>' + Set fill color for solid drawing objects using the RGB color + scheme, having the 3 color components RED, GREEN, and BLUE. + +'Df N<line break>' + The argument N must be an integer in the range -32767 to 32767. + + 0 <= N <= 1000 + Set the color for filling solid drawing objects to a shade of + gray, where 0 corresponds to solid white, 1000 (the default) + to solid black, and values in between to intermediate shades + of gray; this is obsoleted by command 'DFg'. + + N < 0 or N > 1000 + Set the filling color to the color that is currently being + used for the text and the outline, see command 'm'. For + example, the command sequence + + mg 0 0 65535 + Df -1 + + sets all colors to blue. + + No position changing. This command is a 'gtroff' extension. + +'Dl H V<line break>' + Draw line from current position to offset (H,V) (integers in basic + units 'u'); then set current position to the end of the drawn line. + +'Dp H1 V1 H2 V2 ... HN VN<line break>' + Draw a polygon line from current position to offset (H1,V1), from + there to offset (H2,V2), etc., up to offset (HN,VN), and from there + back to the starting position. For historical reasons, the + position is changed by adding the sum of all arguments with odd + index to the actual horizontal position and the even ones to the + vertical position. Although this doesn't make sense it is kept for + compatibility. This command is a 'gtroff' extension. + +'DP H1 V1 H2 V2 ... HN VN<line break>' + Draw a solid polygon in the current fill color rather than an + outlined polygon, using the same arguments and positioning as the + corresponding 'Dp' command. This command is a 'gtroff' extension. + +'Dt N<line break>' + Set the current line thickness to N (an integer in basic units 'u') + if N>0; if N=0 select the smallest available line thickness; if N<0 + set the line thickness proportional to the type size (this is the + default before the first 'Dt' command was specified). For + historical reasons, the horizontal position is changed by adding + the argument to the actual horizontal position, while the vertical + position is not changed. Although this doesn't make sense it is + kept for compatibility. This command is a 'gtroff' extension. + + +File: groff.info, Node: Device Control Commands, Next: Obsolete Command, Prev: Graphics Commands, Up: Command Reference + +6.1.2.4 Device Control Commands +............................... + +Each device control command starts with the letter 'x', followed by a +space character (optional or arbitrary space or tab in 'gtroff') and a +subcommand letter or word; each argument (if any) must be preceded by a +syntactical space. All 'x' commands are terminated by a syntactical +line break; no device control command can be followed by another command +on the same line (except a comment). + + The subcommand is basically a single letter, but to increase +readability, it can be written as a word, i.e., an arbitrary sequence of +characters terminated by the next tab, space, or newline character. All +characters of the subcommand word but the first are simply ignored. For +example, 'gtroff' outputs the initialization command 'x i' as 'x init' +and the resolution command 'x r' as 'x res'. + + In the following, the syntax element <line break> means a syntactical +line break (*note Separation::). + +'xF NAME<line break>' + The 'F' stands for FILENAME. + + Use NAME as the intended name for the current file in error + reports. This is useful for remembering the original file name + when 'gtroff' uses an internal piping mechanism. The input file is + not changed by this command. This command is a 'gtroff' extension. + +'xf N S<line break>' + The 'f' stands for FONT. + + Mount font position N (a non-negative integer) with font named S (a + text word). *Note Font Positions::. + +'xH N<line break>' + The 'H' stands for HEIGHT. + + Set glyph height to N (a positive integer in scaled points 'z'). + AT&T 'troff' uses the unit points ('p') instead. *Note Output + Language Compatibility::. + +'xi<line break>' + The 'i' stands for INIT. + + Initialize device. This is the third command of the prologue. + +'xp<line break>' + The 'p' stands for PAUSE. + + Parsed but ignored. The AT&T 'troff' manual documents this command + as + + pause device, can be restarted + + but GNU 'troff' output drivers do nothing with this command. + +'xr N H V<line break>' + The 'r' stands for RESOLUTION. + + Resolution is N, while H is the minimal horizontal motion, and V + the minimal vertical motion possible with this device; all + arguments are positive integers in basic units 'u' per inch. This + is the second command of the prologue. + +'xS N<line break>' + The 'S' stands for SLANT. + + Set slant to N (an integer in basic units 'u'). + +'xs<line break>' + The 's' stands for STOP. + + Terminates the processing of the current file; issued as the last + command of any intermediate 'troff' output. + +'xt<line break>' + The 't' stands for TRAILER. + + Generate trailer information, if any. In GNU 'troff', this is + ignored. + +'xT XXX<line break>' + The 'T' stands for TYPESETTER. + + Set the name of the output driver to XXX, a sequence of + non-whitespace characters terminated by whitespace. The possible + names correspond to those of 'groff''s '-T' option. This is the + first command of the prologue. + +'xu N<line break>' + The 'u' stands for UNDERLINE. + + Configure underlining of spaces. If N is 1, start underlining of + spaces; if N is 0, stop underlining of spaces. This is needed for + the 'cu' request in 'nroff' mode and is ignored otherwise. This + command is a 'gtroff' extension. + +'xX ANYTHING<line break>' + The 'x' stands for X-ESCAPE. + + Send string ANYTHING uninterpreted to the device. If the line + following this command starts with a '+' character this line is + interpreted as a continuation line in the following sense. The '+' + is ignored, but a newline character is sent instead to the device, + the rest of the line is sent uninterpreted. The same applies to + all following lines until the first character of a line is not a + '+' character. This command is generated by the 'gtroff' escape + sequence '\X'. The line-continuing feature is a 'gtroff' + extension. + + +File: groff.info, Node: Obsolete Command, Prev: Device Control Commands, Up: Command Reference + +6.1.2.5 Obsolete Command +........................ + +In AT&T 'troff' output, the writing of a single glyph is mostly done by +a very strange command that combines a horizontal move and a single +character giving the glyph name. It doesn't have a command code, but is +represented by a 3-character argument consisting of exactly 2 digits and +a character. + +DDG + Move right DD (exactly two decimal digits) basic units 'u', then + print glyph G (represented as a single character). + + In GNU 'troff', arbitrary syntactical space around and within this + command is allowed. Only when a preceding command on the same line + ends with an argument of variable length is a separating space + obligatory. In AT&T 'troff', large clusters of these and other + commands are used, mostly without spaces; this made such output + almost unreadable. + + For modern high-resolution devices, this command does not make sense +because the width of the glyphs can become much larger than two decimal +digits. In 'gtroff', this is only used for the devices 'X75', 'X75-12', +'X100', and 'X100-12'. For other devices, the commands 't' and 'u' +provide a better functionality. + + +File: groff.info, Node: Intermediate Output Examples, Next: Output Language Compatibility, Prev: Command Reference, Up: gtroff Output + +6.1.3 Intermediate Output Examples +---------------------------------- + +This section presents the intermediate output generated from the same +input for three different devices. The input is the sentence 'hell +world' fed into 'gtroff' on the command line. + +High-resolution device 'ps' + + This is the standard output of 'gtroff' if no '-T' option is given. + + shell> echo "hell world" | groff -Z -T ps + + x T ps + x res 72000 1 1 + x init + p1 + x font 5 TR + f5 + s10000 + V12000 + H72000 + thell + wh2500 + tw + H96620 + torld + n12000 0 + x trailer + V792000 + x stop + + This output can be fed into 'grops' to get its representation as a + PostScript file. + +Low-resolution device 'latin1' + + This is similar to the high-resolution device except that the + positioning is done at a minor scale. Some comments (lines + starting with '#') were added for clarification; they were not + generated by the formatter. + + shell> echo "hell world" | groff -Z -T latin1 + + # prologue + x T latin1 + x res 240 24 40 + x init + # begin a new page + p1 + # font setup + x font 1 R + f1 + s10 + # initial positioning on the page + V40 + H0 + # write text 'hell' + thell + # inform about space, and issue a horizontal jump + wh24 + # write text 'world' + tworld + # announce line break, but do nothing because... + n40 0 + # ...the end of the document has been reached + x trailer + V2640 + x stop + + This output can be fed into 'grotty' to get a formatted text + document. + +AT&T 'troff' output + Since a computer monitor has a much lower resolution than modern + printers, the intermediate output for X11 devices can use the + jump-and-write command with its 2-digit displacements. + + shell> echo "hell world" | groff -Z -T X100 + + x T X100 + x res 100 1 1 + x init + p1 + x font 5 TR + f5 + s10 + V16 + H100 + # write text with jump-and-write commands + ch07e07l03lw06w11o07r05l03dh7 + n16 0 + x trailer + V1100 + x stop + + This output can be fed into 'xditview' or 'gxditview' for + displaying in X. + + Due to the obsolete jump-and-write command, the text clusters in + the AT&T 'troff' output are almost unreadable. + + +File: groff.info, Node: Output Language Compatibility, Prev: Intermediate Output Examples, Up: gtroff Output + +6.1.4 Output Language Compatibility +----------------------------------- + +The intermediate output language of AT&T 'troff' was first documented in +'A Typesetter-independent TROFF', by Brian Kernighan, and by 1992 the +AT&T 'troff' manual was updated to incorprate a description of it. + + The GNU 'troff' intermediate output format is compatible with this +specification except for the following features. + + * The classical quasi-device independence is not yet implemented. + + * The old hardware was very different from what we use today. So the + 'groff' devices are also fundamentally different from the ones in + AT&T 'troff'. For example, the AT&T PostScript device is called + 'post' and has a resolution of only 720 units per inch, suitable + for printers 20 years ago, while 'groff''s 'ps' device has a + resolution of 72000 units per inch. Maybe, by implementing some + rescaling mechanism similar to the classical quasi-device + independence, 'groff' could emulate AT&T's 'post' device. + + * The B-spline command 'D~' is correctly handled by the intermediate + output parser, but the drawing routines aren't implemented in some + of the postprocessor programs. + + * The argument of the commands 's' and 'x H' has the implicit unit + scaled point 'z' in 'gtroff', while AT&T 'troff' has point ('p'). + This isn't an incompatibility but a compatible extension, for both + units coincide for all devices without a 'sizescale' parameter in + the 'DESC' file, including all postprocessors from AT&T and + 'groff''s text devices. The few 'groff' devices with a 'sizescale' + parameter either do not exist for AT&T 'troff', have a different + name, or seem to have a different resolution. So conflicts are + very unlikely. + + * The position changing after the commands 'Dp', 'DP', and 'Dt' is + illogical, but as old versions of 'gtroff' used this feature it is + kept for compatibility reasons. + + +File: groff.info, Node: Device and Font Description Files, Prev: gtroff Output, Up: File Formats + +6.2 Device and Font Description Files +===================================== + +The 'groff' font and output device description formats are slight +extensions of those used by AT&T device-independent 'troff'. In +distinction to the AT&T implementation, 'groff' lacks a binary format; +all files are text files.(1) (*note Device and Font Description +Files-Footnote-1::) The device and font description files for a device +NAME are stored in a 'devNAME' directory. The device description file +is called 'DESC', and, for each font supported by the device, a font +description file is called 'F', where F is usually an abbreviation of a +font's name and/or style. For example, the 'ps' (PostScript) device has +'groff' font description files for Times roman ('TR') and Zapf Chancery +Medium italic ('ZCMI'), among many others, while the 'utf8' device (for +terminal emulators) has only font descriptions for the roman, italic, +bold, and bold-italic styles ('R', 'I', 'B', and 'BI', respectively). + + Device and font description files are read both by the formatter, GNU +'troff', and by output drivers. The programs delegate these files' +processing to an internal library, 'libgroff', ensuring their consistent +interpretation. + +* Menu: + +* DESC File Format:: +* Font Description File Format:: + + +File: groff.info, Node: Device and Font Description Files-Footnotes, Up: Device and Font Description Files + + (1) Plan 9 'troff' has also abandoned the binary format. + + +File: groff.info, Node: DESC File Format, Next: Font Description File Format, Prev: Device and Font Description Files, Up: Device and Font Description Files + +6.2.1 'DESC' File Format +------------------------ + +The 'DESC' file contains a series of directives; each begins a line. +Their order is not important, with two exceptions: (1) the 'res' +directive must precede any 'papersize' directive; and (2) the 'charset' +directive must come last (if at all). If a directive name is repeated, +later entries in the file override previous ones (except that the paper +dimensions are computed based on the 'res' directive last seen when +'papersize' is encountered). Spaces and/or tabs separate words and are +ignored at line boundaries. Comments start with the '#' character and +extend to the end of a line. Empty lines are ignored. + +'family FAM' + The default font family is FAM. + +'fonts N F1 ... FN' + Fonts F1, ..., FN are mounted at font positions M+1, ..., M+N where + M is the number of 'styles' (see below). This directive may extend + over more than one line. A font name of '0' causes no font to be + mounted at the corresponding position. + +'hor N' + The horizontal motion quantum is N basic units. All horizontal + quantities are rounded to multiples of N. + +'image_generator PROGRAM' + Use PROGRAM to generate PNG images from PostScript input. Under + GNU/Linux, this is usually 'gs', but under other systems (notably + Cygwin) it might be set to another name. The 'grohtml' driver uses + this directive. + +'paperlength N' + The vertical dimension of the output medium is N basic units + (deprecated: use 'papersize' instead). + +'papersize FORMAT-OR-DIMENSION-PAIR-OR-FILE-NAME ...' + The dimensions of the output medium are as according to the + argument, which is either a standard paper format, a pair of + dimensions, or the name of a plain text file containing either of + the foregoing. + + Recognized paper formats are the ISO and DIN formats 'A0'-'A7', + 'B0'-'B7', 'C0'-'C7', 'D0'-'D7'; the U.S. paper types 'letter', + 'legal', 'tabloid', 'ledger', 'statement', and 'executive'; and the + envelope formats 'com10', 'monarch', and 'DL'. Matching is + performed without regard for lettercase. + + Alternatively, the argument can be a custom paper format in the + format 'LENGTH,WIDTH' (with no spaces before or after the comma). + Both LENGTH and WIDTH must have a unit appended; valid units are + 'i' for inches, 'c' for centimeters, 'p' for points, and 'P' for + picas. Example: '12c,235p'. An argument that starts with a digit + is always treated as a custom paper format. + + Finally, the argument can be a file name (e.g., '/etc/papersize'); + if the file can be opened, the first line is read and a match + attempted against each of the other forms. No comment syntax is + supported. + + More than one argument can be specified; each is scanned in turn + and the first valid paper specification used. + +'paperwidth N' + The horizontal dimension of the output medium is N basic units + (deprecated: use 'papersize' instead). + +'pass_filenames' + Direct GNU 'troff' to emit the name of the source file being + processed. This is achieved with the intermediate output command + 'x F', which 'grohtml' interprets. + +'postpro PROGRAM' + Use PROGRAM as the postprocessor. + +'prepro PROGRAM' + Use PROGRAM as a preprocessor. The 'html' and 'xhtml' output + devices use this directive. + +'print PROGRAM' + Use PROGRAM as a spooler program for printing. If omitted, the + '-l' and '-L' options of 'groff' are ignored. + +'res N' + The device resolution is N basic units per inch. + +'sizes S1 ... SN 0' + The device has fonts at S1, ..., SN scaled points (see below). The + list of sizes must be terminated by '0'. Each SI can also be a + range of sizes M-N. The list can extend over more than one line. + +'sizescale N' + A typographical point is subdivided into N scaled points. The + default is '1'. *Note Using Fractional Type Sizes::. + +'styles S1 ... SM' + The first M mounting positions are associated with styles S1, ..., + SM. + +'tcommand' + The postprocessor can handle the 't' and 'u' intermediate output + commands. + +'unicode' + The output device supports the complete Unicode repertoire. This + directive is useful only for devices that produce character + entities instead of glyphs. + + If 'unicode' is present, no 'charset' section is required in the + font description files since the Unicode handling built into + 'groff' is used. However, if there are entries in a font + description file's 'charset' section, they either override the + default mappings for those particular characters or add new + mappings (normally for composite characters). + + The 'utf8', 'html', and 'xhtml' output devices use this directive. + +'unitwidth N' + Quantities in the font description files are in basic units for + fonts whose type size is N scaled points. + +'unscaled_charwidths' + Make the font handling module always return unscaled character + widths. The 'grohtml' driver uses this directive. + +'use_charnames_in_special' + GNU 'troff' should encode special characters inside device control + commands; see *note Postprocessor Access::. The 'grohtml' driver + uses this directive. + +'vert N' + The vertical motion quantum is N basic units. All vertical + quantities are rounded to multiples of N. + +'charset' + This line and everything following it in the file are ignored. It + is recognized for compatibility with other 'troff' implementations. + In GNU 'troff', character set repertoire is described on a per-font + basis. + + GNU 'troff' recognizes but ignores the directives 'spare1', 'spare2', +and 'biggestfont'. + + The 'res', 'unitwidth', 'fonts', and 'sizes' lines are mandatory. +Directives not listed above are ignored by GNU 'troff' but may be used +by postprocessors to obtain further information about the device. + + +File: groff.info, Node: Font Description File Format, Prev: DESC File Format, Up: Device and Font Description Files + +6.2.2 Font Description File Format +---------------------------------- + +On typesetting output devices, each font is typically available at +multiple sizes. While paper measurements in the device description file +are in absolute units, measurements applicable to fonts must be +proportional to the type size. 'groff' achieves this using the +precedent set by AT&T device-independent 'troff': one font size is +chosen as a norm, and all others are scaled linearly relative to that +basis. The "unit width" is the number of basic units per point when the +font is rendered at this nominal size. + + For instance, 'groff''s 'lbp' device uses a 'unitwidth' of 800. Its +Times roman font 'TR' has a 'spacewidth' of 833; this is also the width +of its comma, period, centered period, and mathematical asterisk, while +its 'M' is 2,963 basic units. Thus, an 'M' on the 'lbp' device is 2,963 +basic units wide at a notional type size of 800 points.(1) (*note Font +Description File Format-Footnote-1::) + + A font description file has two sections. The first is a sequence of +directives, and is parsed similarly to the 'DESC' file described above. +Except for the directive names that begin the second section, their +ordering is immaterial. Later directives of the same name override +earlier ones, spaces and tabs are handled in the same way, and the same +comment syntax is supported. Empty lines are ignored throughout. + +'name F' + The name of the font is F. 'DESC' is an invalid font name. Simple + integers are valid, but their use is discouraged.(2) (*note Font + Description File Format-Footnote-2::) + +'spacewidth N' + The width of an unadjusted inter-word space is N basic units. + + The directives above must appear in the first section; those below +are optional. + +'slant N' + The font's glyphs have a slant of N degrees; a positive N slants in + the direction of text flow. + +'ligatures LIG1 ... LIGN [0]' + Glyphs LIG1, ..., LIGN are ligatures; possible ligatures are 'ff', + 'fi', 'fl', 'ffi' and 'ffl'. For compatibility with other 'troff' + implementations, the list of ligatures may be terminated with + a '0'. The list of ligatures must not extend over more than one + line. + +'special' + The font is "special": when a glyph is requested that is not + present in the current font, it is sought in any mounted fonts that + bear this property. + + Other directives in this section are ignored by GNU 'troff', but may +be used by postprocessors to obtain further information about the font. + + The second section contains one or two subsections. These can appear +in either order; the first one encountered commences the second section. +Each starts with a directive on a line by itself. A 'charset' +subsection is mandatory unless the associated 'DESC' file contains the +'unicode' directive. Another subsection, 'kernpairs', is optional. + + The directive 'charset' starts the character set subsection.(3) +(*note Font Description File Format-Footnote-3::) It precedes a series +of glyph descriptions, one per line. Each such glyph description +comprises a set of fields separated by spaces or tabs and organized as +follows. + + NAME METRICS TYPE CODE [ENTITY-NAME] ['--' COMMENT] + +NAME identifies the glyph: if NAME is a printable character C, it +corresponds to the 'troff' ordinary character C. If NAME is a +multi-character sequence not beginning with '\', it corresponds to the +GNU 'troff' special character escape sequence '\[NAME]'. A name +consisting of three minus signs, '---', is special and indicates that +the glyph is unnamed: such glyphs can be accessed only by the '\N' +escape sequence in 'troff'. A special character named '---' can still +be defined using 'char' and similar requests. The NAME '\-' defines the +minus sign glyph. Finally, NAME can be the unbreakable one-sixth and +one-twelfth space escape sequences, '\|' and '\^' ("thin" and "hair" +spaces, respectively), in which case only the width metric described +below is interpreted; a font can thus customize the widths of these +spaces. + + The form of the METRICS field is as follows. + + WIDTH[','[HEIGHT[','[DEPTH[','[ITALIC-CORRECTION + [','[LEFT-ITALIC-CORRECTION[','[SUBSCRIPT-CORRECTION]]]]]]]]]] + +There must not be any spaces, tabs, or newlines between these +"subfields" (which have been split here into two lines only for better +legibility). The subfields are in basic units expressed as decimal +integers. Unspecified subfields default to '0'. Since there is no +associated binary format, these values are not required to fit into the +C language data type 'char' as they are in AT&T device-independent +'troff'. + + The WIDTH subfield gives the width of the glyph. The HEIGHT subfield +gives the height of the glyph (upward is positive); if a glyph does not +extend above the baseline, it should be given a zero height, rather than +a negative height. The DEPTH subfield gives the depth of the glyph, +that is, the distance below the baseline to which the glyph extends +(downward is positive); if a glyph does not extend below the baseline, +it should be given a zero depth, rather than a negative depth. Italic +corrections are relevant to glyphs in italic or oblique styles. The +ITALIC-CORRECTION is the amount of space that should be added after an +oblique glyph to be followed immediately by an upright glyph. The +LEFT-ITALIC-CORRECTION is the amount of space that should be added +before an oblique glyph to be preceded immediately by an upright glyph. +The SUBSCRIPT-CORRECTION is the amount of space that should be added +after an oblique glyph to be followed by a subscript; it should be less +than the italic correction. + + For fonts used with typesetting devices, the TYPE field gives a +featural description of the glyph: it is a bit mask recording whether +the glyph is an ascender, descender, both, or neither. When a '\w' +escape sequence is interpolated, these values are bitwise or-ed together +for each glyph and stored in the 'nr' register. In font descriptions +for terminal devices, all glyphs might have a type of zero, regardless +of their appearance. + +'0' + means the glyph lies entirely between the baseline and a horizontal + line at the "x-height" of the font; typical examples are 'a', 'c', + and 'x'; + +'1' + means the glyph descends below the baseline, like 'p'; + +'2' + means the glyph ascends above the font's x-height, like 'A' or 'b'; + and + +'3' + means the glyph is both an ascender and a descender--this is true + of parentheses in some fonts. + + The CODE field gives a numeric identifier that the postprocessor uses +to render the glyph. The glyph can be specified to 'troff' using this +code by means of the '\N' escape sequence. CODE can be any integer.(4) +(*note Font Description File Format-Footnote-4::) + + The ENTITY-NAME field defines an identifier for the glyph that the +postprocessor uses to print the GNU 'troff' glyph NAME. This field is +optional; it was introduced so that the 'grohtml' output driver could +encode its character set. For example, the glyph '\[Po]' is represented +by '£' in HTML 4.0. For efficiency, these data are now compiled +directly into 'grohtml'. 'grops' uses the field to build sub-encoding +arrays for PostScript fonts containing more than 256 glyphs. Anything +on the line after the ENTITY-NAME field or '--' is ignored. + + A line in the 'charset' section can also have the form + + NAME " + +identifying NAME as another name for the glyph mentioned in the +preceding line. Such aliases can be chained. + + The directive 'kernpairs' starts a list of kerning adjustments to be +made to adjacent glyph pairs from this font. It contains a sequence of +lines formatted as follows. + + G1 G2 N + +The foregoing means that when glyph G1 is typeset immediately before G2, +the space between them should be increased by N. Most kerning pairs +should have a negative value for N. + + +File: groff.info, Node: Font Description File Format-Footnotes, Up: Font Description File Format + + (1) 800-point type is not practical for most purposes, but using it +enables the quantities in the font description files to be expressed as +integers. + + (2) 'groff' requests and escape sequences interpret non-negative font +names as mounting positions instead. Further, a font named '0' cannot +be automatically mounted by the 'fonts' directive of a 'DESC' file. + + (3) For typesetter devices, this directive is misnamed since it +starts a list of glyphs, not characters. + + (4) that is, any integer parsable by the C standard library's +'strtol(3)' function + + +File: groff.info, Node: Copying This Manual, Next: Request Index, Prev: Font Description File Format, Up: Top + +Appendix A Copying This Manual +****************************** + + Version 1.3, 3 November 2008 + + Copyright © 2000-2018 Free Software Foundation, Inc. + <http://fsf.org/> + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + <http://www.gnu.org/copyleft/>. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: groff.info, Node: Request Index, Next: Escape Sequence Index, Prev: Copying This Manual, Up: Top + +Appendix B Request Index +************************ + +Request names appear without a leading control character; the defaults +are '.' for the regular control character and ''' for the no-break +control character. + + +* Menu: + +* ab: Debugging. (line 55) +* ad: Manipulating Filling and Adjustment. + (line 83) +* af: Assigning Register Formats. + (line 12) +* aln: Setting Registers. (line 110) +* als: Strings. (line 198) +* am: Writing Macros. (line 126) +* am1: Writing Macros. (line 127) +* ami: Writing Macros. (line 128) +* ami1: Writing Macros. (line 129) +* as: Strings. (line 114) +* as1: Strings. (line 115) +* asciify: Diversions. (line 208) +* backtrace: Debugging. (line 104) +* bd: Artificial Fonts. (line 95) +* blm: Blank Line Traps. (line 7) +* box: Diversions. (line 63) +* boxa: Diversions. (line 64) +* bp: Page Control. (line 11) +* br: Manipulating Filling and Adjustment. + (line 39) +* break: while. (line 72) +* brp: Manipulating Filling and Adjustment. + (line 156) +* c2: Control Characters. (line 29) +* cc: Control Characters. (line 23) +* ce: Manipulating Filling and Adjustment. + (line 208) +* cf: I/O. (line 58) +* cflags: Using Symbols. (line 252) +* ch: Page Location Traps. (line 114) +* char: Using Symbols. (line 351) +* chop: Strings. (line 145) +* class: Character Classes. (line 12) +* close: I/O. (line 240) +* color: Colors. (line 15) +* composite: Using Symbols. (line 208) +* continue: while. (line 76) +* cp: Compatibility Mode. (line 16) +* cs: Artificial Fonts. (line 125) +* cu: Artificial Fonts. (line 86) +* da: Diversions. (line 32) +* de: Writing Macros. (line 14) +* de1: Writing Macros. (line 86) +* defcolor: Colors. (line 27) +* dei: Writing Macros. (line 108) +* dei1: Writing Macros. (line 109) +* device: Postprocessor Access. + (line 15) +* devicem: Postprocessor Access. + (line 45) +* di: Diversions. (line 31) +* do: Compatibility Mode. (line 27) +* ds: ms Document Control Settings. + (line 15) +* ds <1>: Strings. (line 24) +* ds1: Strings. (line 25) +* dt: Diversion Traps. (line 11) +* ec: Using Escape Sequences. + (line 76) +* ecr: Using Escape Sequences. + (line 102) +* ecs: Using Escape Sequences. + (line 101) +* el: if-else. (line 8) +* em: End-of-input Traps. (line 7) +* eo: Using Escape Sequences. + (line 71) +* ev: Environments. (line 46) +* evc: Environments. (line 100) +* ex: Debugging. (line 60) +* fam: Font Families. (line 21) +* fc: Fields. (line 18) +* fchar: Using Symbols. (line 352) +* fcolor: Colors. (line 85) +* fi: Manipulating Filling and Adjustment. + (line 66) +* fl: Debugging. (line 95) +* fp: Font Positions. (line 16) +* fschar: Using Symbols. (line 353) +* fspecial: Special Fonts. (line 18) +* ft: Selecting Fonts. (line 11) +* ftr: Selecting Fonts. (line 69) +* fzoom: Selecting Fonts. (line 83) +* gcolor: Colors. (line 57) +* hc: Manipulating Hyphenation. + (line 88) +* hcode: Manipulating Hyphenation. + (line 293) +* hla: Manipulating Hyphenation. + (line 327) +* hlm: Manipulating Hyphenation. + (line 340) +* hpf: Manipulating Hyphenation. + (line 233) +* hpfa: Manipulating Hyphenation. + (line 234) +* hpfcode: Manipulating Hyphenation. + (line 235) +* hw: Manipulating Hyphenation. + (line 22) +* hy: Manipulating Hyphenation. + (line 120) +* hym: Manipulating Hyphenation. + (line 354) +* hys: Manipulating Hyphenation. + (line 369) +* ie: if-else. (line 7) +* if: if-then. (line 7) +* ig: Comments. (line 54) +* in: Line Layout. (line 86) +* it: Input Line Traps. (line 7) +* itc: Input Line Traps. (line 8) +* kern: Ligatures and Kerning. + (line 41) +* lc: Leaders. (line 22) +* length: Strings. (line 135) +* lf: Debugging. (line 31) +* lg: Ligatures and Kerning. + (line 23) +* linetabs: Tabs and Fields. (line 139) +* ll: Line Layout. (line 138) +* ls: Manipulating Spacing. + (line 57) +* lsm: Leading Space Traps. (line 7) +* lt: Page Layout. (line 53) +* mc: Miscellaneous. (line 110) +* mk: Page Motions. (line 10) +* mso: I/O. (line 49) +* msoquiet: I/O. (line 50) +* na: Manipulating Filling and Adjustment. + (line 150) +* ne: Page Control. (line 31) +* nf: Manipulating Filling and Adjustment. + (line 74) +* nh: Manipulating Hyphenation. + (line 228) +* nm: Miscellaneous. (line 9) +* nn: Miscellaneous. (line 74) +* nop: if-then. (line 26) +* nr: ms Document Control Settings. + (line 11) +* nr <1>: Setting Registers. (line 10) +* nr <2>: Setting Registers. (line 64) +* nr <3>: Auto-increment. (line 14) +* nroff: troff and nroff Modes. + (line 33) +* ns: Manipulating Spacing. + (line 116) +* nx: I/O. (line 90) +* open: I/O. (line 207) +* opena: I/O. (line 208) +* os: Page Control. (line 66) +* output: Diversions. (line 195) +* pc: Page Layout. (line 68) +* pev: Debugging. (line 78) +* pi: I/O. (line 149) +* pl: Page Layout. (line 9) +* pm: Debugging. (line 82) +* pn: Page Layout. (line 23) +* pnr: Debugging. (line 86) +* po: Line Layout. (line 60) +* ps: Changing the Type Size. + (line 7) +* psbb: Miscellaneous. (line 158) +* pso: I/O. (line 38) +* ptr: Debugging. (line 90) +* pvs: Changing the Vertical Spacing. + (line 48) +* rchar: Using Symbols. (line 410) +* rd: I/O. (line 95) +* return: Writing Macros. (line 163) +* rfschar: Using Symbols. (line 411) +* rj: Manipulating Filling and Adjustment. + (line 247) +* rm: Strings. (line 193) +* rn: Strings. (line 190) +* rnn: Setting Registers. (line 105) +* rr: Setting Registers. (line 99) +* rs: Manipulating Spacing. + (line 117) +* rt: Page Motions. (line 11) +* schar: Using Symbols. (line 354) +* shc: Manipulating Hyphenation. + (line 97) +* shift: Parameters. (line 30) +* sizes: Changing the Type Size. + (line 71) +* so: I/O. (line 9) +* soquiet: I/O. (line 10) +* sp: Manipulating Spacing. + (line 10) +* special: Special Fonts. (line 17) +* spreadwarn: Debugging. (line 135) +* ss: Manipulating Filling and Adjustment. + (line 267) +* stringdown: Strings. (line 170) +* stringup: Strings. (line 171) +* sty: Font Families. (line 62) +* substring: Strings. (line 153) +* sv: Page Control. (line 65) +* sy: I/O. (line 171) +* ta: Tabs and Fields. (line 13) +* tag: Postprocessor Access. + (line 58) +* taga: Postprocessor Access. + (line 59) +* tc: Tabs and Fields. (line 127) +* ti: Line Layout. (line 110) +* tkf: Ligatures and Kerning. + (line 60) +* tl: Page Layout. (line 39) +* tm: Debugging. (line 43) +* tm1: Debugging. (line 44) +* tmc: Debugging. (line 45) +* tr: Character Translations. + (line 13) +* trf: I/O. (line 57) +* trin: Character Translations. + (line 14) +* trnt: Character Translations. + (line 79) +* troff: troff and nroff Modes. + (line 25) +* uf: Artificial Fonts. (line 90) +* ul: Artificial Fonts. (line 64) +* unformat: Diversions. (line 233) +* vpt: Vertical Position Traps. + (line 13) +* vs: Changing the Vertical Spacing. + (line 7) +* warn: Debugging. (line 154) +* warnscale: Debugging. (line 131) +* wh: Page Location Traps. (line 11) +* while: while. (line 10) +* write: I/O. (line 219) +* writec: I/O. (line 220) +* writem: I/O. (line 231) + |