diff options
Diffstat (limited to 'contrib/groff/doc/groff-2')
| -rw-r--r-- | contrib/groff/doc/groff-2 | 5755 |
1 files changed, 4549 insertions, 1206 deletions
diff --git a/contrib/groff/doc/groff-2 b/contrib/groff/doc/groff-2 index 052ac1258b48..1861ac7254e3 100644 --- a/contrib/groff/doc/groff-2 +++ b/contrib/groff/doc/groff-2 @@ -1,9 +1,9 @@ -This is groff, produced by makeinfo version 4.3d from ./groff.texinfo. +This is groff, produced by makeinfo version 4.8 from ./groff.texinfo. -This manual documents GNU `troff' version 1.19. + This manual documents GNU `troff' version 1.19.2. - Copyright (C) 1994-2000, 2001, 2002, 2003 Free Software Foundation, -Inc. + Copyright (C) 1994-2000, 2001, 2002, 2003, 2004, 2005 Free Software +Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -16,1552 +16,4895 @@ Inc. (a) The FSF's Back-Cover Text is: `You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." - + INFO-DIR-SECTION Typesetting START-INFO-DIR-ENTRY * Groff: (groff). The GNU troff document formatting system. END-INFO-DIR-ENTRY -File: groff, Node: Man options, Next: Man usage, Prev: man, Up: man +File: groff, Node: Drawing Requests, Next: Traps, Prev: Page Motions, Up: gtroff Reference + +5.23 Drawing Requests +===================== + +`gtroff' provides a number of ways to draw lines and other figures on +the page. Used in combination with the page motion commands (see *Note +Page Motions::, for more info), a wide variety of figures can be drawn. +However, for complex drawings these operations can be quite +cumbersome, and it may be wise to use graphic preprocessors like `gpic' +or `ggrn'. *Note gpic::, and *Note ggrn::, for more information. + + All drawing is done via escapes. + + -- Escape: \l'l' + -- Escape: \l'lg' + Draw a line horizontally. L is the length of the line to be + drawn. If it is positive, start the line at the current location + and draw to the right; its end point is the new current location. + Negative values are handled differently: The line starts at the + current location and draws to the left, but the current location + doesn't move. + + L can also be specified absolutely (i.e. with a leading `|') which + draws back to the beginning of the input line. Default scaling + indicator is `m'. + + The optional second parameter G is a glyph to draw the line with. + If this second argument is not specified, `gtroff' uses the + underscore glyph, `\[ru]'. + + To separate the two arguments (to prevent `gtroff' from + interpreting a drawing glyph as a scaling indicator if the glyph is + represented by a single character) use `\&'. + + Here a small useful example: + + + .de box + \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' + .. + + Note that this works by outputting a box rule (a vertical line), + then the text given as an argument and then another box rule. + Finally, the line drawing escapes both draw from the current + location to the beginning of the _input_ line - this works because + the line length is negative, not moving the current point. + + -- Escape: \L'l' + -- Escape: \L'lg' + Draw vertical lines. Its parameters are similar to the `\l' + escape, except that the default scaling indicator is `v'. The + movement is downwards for positive values, and upwards for + negative values. The default glyph is the box rule glyph, + `\[br]'. As with the vertical motion escapes, text processing + blindly continues where the line ends. + + + This is a \L'3v'test. + + Here the result, produced with `grotty'. + + + This is a + | + | + |test. + + + -- Escape: \D'command arg ...' + The `\D' escape provides a variety of drawing functions. Note + that on character devices, only vertical and horizontal lines are + supported within `grotty'; other devices may only support a subset + of the available drawing functions. + + The default scaling indicator for all subcommands of `\D' is `m' + for horizontal distances and `v' for vertical ones. Exceptions + are `\D'f ...'' and `\D't ...'' which use `u' as the default, and + `\D'FX ...'' which arguments are treated similar to the `defcolor' + request. + + `\D'l DX DY'' + Draw a line from the current location to the relative point + specified by (DX,DY), where positive values mean down and + right, respectively. The end point of the line is the new + current location. + + The following example is a macro for creating a box around a + text string; for simplicity, the box margin is taken as a + fixed value, 0.2m. + + + .de BOX + . 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' + .. + + First, the width of the string is stored in register `@wd'. + Then, four lines are drawn to form a box, properly offset by + the box margin. The registers `rst' and `rsb' are set by the + `\w' escape, containing the largest height and depth of the + whole string. + + `\D'c D'' + Draw a circle with a diameter of D with the leftmost point at + the current position. After drawing, the current location is + positioned at the rightmost point of the circle. + + `\D'C D'' + Draw a solid circle with the same parameters and behaviour as + an outlined circle. No outline is drawn. + + `\D'e X Y'' + Draw an ellipse with a horizontal diameter of X and a vertical + diameter of Y with the leftmost point at the current position. + After drawing, the current location is positioned at the + rightmost point of the ellipse. + + `\D'E X Y'' + Draw a solid ellipse with the same parameters and behaviour + as an outlined ellipse. No outline is drawn. + + `\D'a DX1 DY1 DX2 DY2'' + Draw an arc clockwise from the current location through the + two specified relative locations (DX1,DY1) and (DX2,DY2). + The coordinates of the first point are relative to the + current position, and the coordinates of the second point are + relative to the first point. After drawing, the current + position is moved to the final point of the arc. + + `\D'~ DX1 DY1 DX2 DY2 ...'' + Draw a spline from the current location to the relative point + (DX1,DY1) and then to (DX2,DY2), and so on. The current + position is moved to the terminal point of the drawn curve. + + `\D'f N'' + Set the shade of gray to be used for filling solid objects + to N; N must be an integer between 0 and 1000, where 0 + corresponds solid white and 1000 to solid black, and values + in between correspond to intermediate shades of gray. This + applies only to solid circles, solid ellipses, and solid + polygons. By default, a level of 1000 is used. + + Despite of being silly, the current point is moved + horizontally to the right by N. + + Don't use this command! It has the serious drawback that it + will be always rounded to the next integer multiple of the + horizontal resolution (the value of the `hor' keyword in the + `DESC' file). Use `\M' (*note Colors::) or `\D'Fg ...'' + instead. + + `\D'p DX1 DY1 DX2 DY2 ...'' + Draw a polygon from the current location to the relative + position (DX1,DY1) and then to (DX2,DY2) and so on. When the + specified data points are exhausted, a line is drawn back to + the starting point. The current 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. + + `\D'P DX1 DY1 DX2 DY2 ...'' + Draw a solid polygon with the same parameters and behaviour + as an outlined polygon. No outline is drawn. + + Here a better variant of the box macro to fill the box with + some color. Note that the box must be drawn before the text + since colors in `gtroff' are not transparent; the filled + polygon would hide the text completely. + + + .de BOX + . 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 current line thickness to N machine units. A value of + zero selects the smallest available line thickness. A + negative value makes the line thickness proportional to the + current point size (this is the default behaviour of AT&T + `troff'). + + Despite of being silly, the current point is moved + horizontally to the right by N. + + `\D'FSCHEME COLOR_COMPONENTS'' + Change current fill color. SCHEME is a single letter + denoting the color scheme: `r' (rgb), `c' (cmy), `k' (cmyk), + `g' (gray), or `d' (default color). The color components use + exactly the same syntax as in the `defcolor' request (*note + Colors::); the command `\D'Fd'' doesn't take an argument. + + _No_ position changing! + + Examples: + + + \D'Fg .3' \" same gray as \D'f 700' \D'Fr #0000ff' \" + blue + + *Note Graphics Commands::. + + -- Escape: \b'string' + "Pile" a sequence of glyphs vertically, and center it vertically + on the current line. Use it to build large brackets and braces. + + Here an example how to create a large opening brace: + + + \b'\[lt]\[bv]\[lk]\[bv]\[lb]' + + The first glyph is on the top, the last glyph in STRING is at the + bottom. Note that `gtroff' separates the glyphs vertically by 1m, + and the whole object is centered 0.5m above the current baseline; + the largest glyph width is used as the width for the whole object. + This rather unflexible positioning algorithm doesn't work with + `-Tdvi' since the bracket pieces vary in height for this device. + Instead, use the `eqn' preprocessor. + + *Note Manipulating Spacing::, how to adjust the vertical spacing + with the `\x' escape. + + +File: groff, Node: Traps, Next: Diversions, Prev: Drawing Requests, Up: gtroff Reference -Options -------- +5.24 Traps +========== - The command line format for using the `man' macros with `groff' is: +"Traps" are locations, which, when reached, call a specified macro. +These traps can occur at a given location on the page, at a given +location in the current diversion, at a blank line, after a certain +number of input lines, or at the end of input. + Setting a trap is also called "planting". It is also said that a +trap is "sprung" if the associated macro is executed. - groff -m man [ -rLL=LENGTH ] [ -rLT=LENGTH ] [ -rFT=DIST ] - [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=FLAGS ] - [ -rPNNN ] [ -rSXX ] [ -rXNNN ] - [ -rIN=LENGTH ] [ -rSN=LENGTH ] [ FILES... ] +* Menu: -It is possible to use `-man' instead of `-m man'. +* Page Location Traps:: +* Diversion Traps:: +* Input Line Traps:: +* Blank Line Traps:: +* End-of-input Traps:: -`-rcR=1' - This option (the default if a TTY output device is used) creates a - single, very long page instead of multiple pages. Use `-rcR=0' to - disable it. + +File: groff, Node: Page Location Traps, Next: Diversion Traps, Prev: Traps, Up: Traps -`-rC1' - If more than one manual page is given on the command line, number - the pages continuously, rather than starting each at 1. - -`-rD1' - Double-sided printing. Footers for even and odd pages are - formatted differently. - -`-rFT=DIST' - Set the position of the footer text to DIST. If positive, the - distance is measured relative to the top of the page, otherwise it - is relative to the bottom. The default is -0.5i. - -`-rHY=FLAGS' - Set hyphenation flags. Possible values are 1 to hyphenate without - restrictions, 2 to not hyphenate the last word on a page, 4 to - not hyphenate the last two characters of a word, and 8 to not - hyphenate the first two characters of a word. These values are - additive; the default is 14. - -`-rIN=LENGTH' - Set the body text indent to LENGTH. If not specified, the indent - defaults to 7n (7 characters) in nroff mode and 7.2n otherwise. - For nroff, this value should always be an integer multiple of unit - `n' to get consistent indentation. - -`-rLL=LENGTH' - Set line length to LENGTH. If not specified, the line length - defaults to 78 en in nroff mode (this is 78 characters per line) - and 6.5 inch otherwise. - -`-rLT=LENGTH' - Set title length to LENGTH. If not specified, the title length - defaults to the line length. - -`-rPNNN' - Page numbering starts with NNN rather than with 1. - -`-rSXX' - Use XX (which can be 10, 11, or 12pt) as the base document font - size instead of the default value of 10pt. - -`-rSN=LENGTH' - Set the indent for sub-subheadings to LENGTH. If not specified, - the indent defaults to 3n. - -`-rXNNN' - After page NNN, number pages as NNNa, NNNb, NNNc, etc. For - example, the option `-rX2' produces the following page numbers: 1, - 2, 2a, 2b, 2c, etc. - - -File: groff, Node: Man usage, Next: Man font macros, Prev: Man options, Up: man - -Usage ------ - - This section describes the available macros for manual pages. For -further customization, put additional macros and requests into the file -`man.local' which is loaded immediately after the `man' package. - - - Macro: .TH title section [extra1 [extra2 [extra3]]] - Set the title of the man page to TITLE and the section to SECTION, - which must have a value between 1 and 8. The value of SECTION may - also have a string appended, e.g. `.pm', to indicate a specific - subsection of the man pages. - - Both TITLE and SECTION are positioned at the left and right in the - header line (with SECTION in parentheses immediately appended to - TITLE. EXTRA1 is positioned in the middle of the footer line. - EXTRA2 is positioned at the left in the footer line (or at the - left on even pages and at the right on odd pages if double-sided - printing is active). EXTRA3 is centered in the header line. - - For HTML output, headers and footers are completely suppressed. - - Additionally, this macro starts a new page; the new line number - is 1 again (except if the `-rC1' option is given on the command - line) - this feature is intended only for formatting multiple man - pages; a single man page should contain exactly one `TH' macro at - the beginning of the file. - - - Macro: .SH [heading] - Set up an unnumbered section heading sticking out to the left. - Prints out all the text following `SH' up to the end of the line - (or the text in the next line if there is no argument to `SH') in - bold face (or the font specified by the string `HF'), one size - larger than the base document size. Additionally, the left margin - and the indentation for the following text is reset to its default - value. - - - Macro: .SS [heading] - Set up an unnumbered (sub)section heading. Prints out all the text - following `SS' up to the end of the line (or the text in the next - line if there is no argument to `SS') in bold face (or the font - specified by the string `HF'), at the same size as the base - document size. Additionally, the left margin and the indentation - for the following text is reset to its default value. - - - Macro: .TP [nnn] - Set up an indented paragraph with label. The indentation is set to - NNN if that argument is supplied (the default unit is `n' if - omitted), otherwise it is set to the previous indentation value - specified with `TP', `IP', or `HP' (or to the default value if - none of them have been used yet). - - The first line of text following this macro is interpreted as a - string to be printed flush-left, as it is appropriate for a label. - It is not interpreted as part of a paragraph, so there is no - attempt to fill the first line with text from the following input - lines. Nevertheless, if the label is not as wide as the - indentation the paragraph starts at the same line (but indented), - continuing on the following lines. If the label is wider than the - indentation the descriptive part of the paragraph begins on the - line following the label, entirely indented. Note that neither - font shape nor font size of the label is set to a default value; - on the other hand, the rest of the text has default font settings. - - - Macro: .LP - - Macro: .PP - - Macro: .P - These macros are mutual aliases. Any of them causes a line break - at the current position, followed by a vertical space downwards by - the amount specified by the `PD' macro. The font size and shape - are reset to the default value (10pt roman if no `-rS' option is - given on the command line). Finally, the current left margin and - the indentation is restored. - - - Macro: .IP [designator [nnn]] - Set up an indented paragraph, using DESIGNATOR as a tag to mark - its beginning. The indentation is set to NNN if that argument is - supplied (default unit is `n'), otherwise it is set to the - previous indentation value specified with `TP', `IP', or `HP' (or - the default value if none of them have been used yet). Font size - and face of the paragraph (but not the designator) are reset to - their default values. - - To start an indented paragraph with a particular indentation but - without a designator, use `""' (two double quotes) as the first - argument of `IP'. - - For example, to start a paragraph with bullets as the designator - and 4 en indentation, write - - - .IP \(bu 4 - - - - Macro: .HP [nnn] - Set up a paragraph with hanging left indentation. The indentation - is set to NNN if that argument is supplied (default unit is `n'), - otherwise it is set to the previous indentation value specified - with `TP', `IP', or `HP' (or the default value if non of them have - been used yet). Font size and face are reset to their default - values. - - - Macro: .RS [nnn] - Move the left margin to the right by the value NNN if specified - (default unit is `n'); otherwise it is set to the previous - indentation value specified with `TP', `IP', or `HP' (or to the - default value if none of them have been used yet). The - indentation value is then set to the default. - - Calls to the `RS' macro can be nested. - - - Macro: .RE [nnn] - Move the left margin back to level NNN, restoring the previous left - margin. If no argument is given, it moves one level back. The - first level (i.e., no call to `RS' yet) has number 1, and each call - to `RS' increases the level by 1. - - To summarize, the following macros cause a line break with the -insertion of vertical space (which amount can be changed with the `PD' -macro): `SH', `SS', `TP', `LP' (`PP', `P'), `IP', and `HP'. - - The macros `RS' and `RE' also cause a break but do not insert -vertical space. - - Finally, the macros `SH', `SS', `LP' (`PP', `P'), and `RS' reset the -indentation to its default value. - - -File: groff, Node: Man font macros, Next: Miscellaneous man macros, Prev: Man usage, Up: man - -Macros to set fonts -------------------- +5.24.1 Page Location Traps +-------------------------- - The standard font is roman; the default text size is 10 point. If -command line option `-rS=N' is given, use Npt as the default text size. +"Page location traps" perform an action when `gtroff' reaches or passes +a certain vertical location on the page. Page location traps have a +variety of purposes, including: + + * setting headers and footers + + * setting body text in multiple columns + + * setting footnotes + + -- Request: .vpt flag + -- Register: \n[.vpt] + Enable vertical position traps if FLAG is non-zero, or disables + them otherwise. Vertical position traps are traps set by the `wh' + or `dt' requests. Traps set by the `it' request are not vertical + position traps. The parameter that controls whether vertical + position traps are enabled is global. Initially vertical position + traps are enabled. The current setting of this is available in the + `.vpt' read-only number register. + + Note that a page can't be ejected if `vpt' is set to zero. + + -- Request: .wh dist [macro] + Set a page location trap. Non-negative values for DIST set the + trap relative to the top of the page; negative values set the trap + relative to the bottom of the page. Default scaling indicator is + `v'. + + MACRO is the name of the macro to execute when the trap is sprung. + If MACRO is missing, remove the first trap (if any) at DIST. + + The following is a simple example of how many macro packages set + headers and footers. + + + .de hd \" Page header + ' sp .5i + . tl 'Title''date' + ' sp .3i + .. + . + .de fo \" Page footer + ' sp 1v + . tl ''%'' + ' bp + .. + . + .wh 0 hd \" trap at top of the page + .wh -1i fo \" trap one inch from bottom + + A trap at or below the bottom of the page is ignored; it can be + made active by either moving it up or increasing the page length + so that the trap is on the page. + + It is possible to have more than one trap at the same location; to + do so, the traps must be defined at different locations, then + moved together with the `ch' request; otherwise the second trap + would replace the first one. Earlier defined traps hide later + defined traps if moved to the same position (the many empty lines + caused by the `bp' request are omitted in the following example): + + + .de a + . nop a + .. + .de b + . nop b + .. + .de c + . nop c + .. + . + .wh 1i a + .wh 2i b + .wh 3i c + .bp + => a b c + + + .ch b 1i + .ch c 1i + .bp + => a + + + .ch a 0.5i + .bp + => a b + + + -- Register: \n[.t] + A read-only number register holding the distance to the next trap. + + If there are no traps between the current position and the bottom + of the page, it contains the distance to the page bottom. In a + diversion, the distance to the page bottom is infinite (the + returned value is the biggest integer which can be represented in + `groff') if there are no diversion traps. + + -- Request: .ch macro [dist] + Change the location of a trap. The first argument is the name of + the macro to be invoked at the trap, and the second argument is + the new location for the trap (note that the parameters are + specified in opposite order as in the `wh' request). This is + useful for building up footnotes in a diversion to allow more + space at the bottom of the page for them. + + Default scaling indicator for DIST is `v'. If DIST is missing, + the trap is removed. + + + -- Register: \n[.ne] + The read-only number register `.ne' contains the amount of space + that was needed in the last `ne' request that caused a trap to be + sprung. Useful in conjunction with the `.trunc' register. *Note + Page Control::, for more information. + + Since the `.ne' register is only set by traps it doesn't make much + sense to use it outside of trap macros. + + -- Register: \n[.trunc] + A read-only register containing the amount of vertical space + truncated by the most recently sprung vertical position trap, or, + if the trap was sprung by an `ne' request, minus the amount of + vertical motion produced by the `ne' request. In other words, at + the point a trap is sprung, it represents the difference of what + the vertical position would have been but for the trap, and what + the vertical position actually is. + + Since the `.trunc' register is only set by traps it doesn't make + much sense to use it outside of trap macros. + + -- Register: \n[.pe] + A read-only register which is set to 1 while a page is ejected with + the `bp' request (or by the end of input). + + Outside of traps this register is always zero. In the following + example, only the second call to `x' is caused by `bp'. + + + .de x + \&.pe=\\n[.pe] + .br + .. + .wh 1v x + .wh 4v x + A line. + .br + Another line. + .br + => A line. + .pe=0 + Another line. + + .pe=1 + + + An important fact to consider while designing macros is that +diversions and traps do not interact normally. For example, if a trap +invokes a header macro (while outputting a diversion) which tries to +change the font on the current page, the effect will not be visible +before the diversion has completely been printed (except for input +protected with `\!' or `\?') since the data in the diversion is already +formatted. In most cases, this is not the expected behaviour. - - Macro: .SM [text] - Set the text on the same line or the text on the next line in a - font that is one point size smaller than the default font. + +File: groff, Node: Diversion Traps, Next: Input Line Traps, Prev: Page Location Traps, Up: Traps - - Macro: .SB [text] - Set the text on the same line or the text on the next line in bold - face font, one point size smaller than the default font. +5.24.2 Diversion Traps +---------------------- - - Macro: .BI text - Set its arguments alternately in bold face and italic, without a - space between the arguments. Thus, + -- Request: .dt [dist macro] + Set a trap _within_ a diversion. DIST is the location of the trap + (identical to the `wh' request; default scaling indicator is `v') + and MACRO is the name of the macro to be invoked. If called + without arguments, the diversion trap is removed. + Note that there exists only a single diversion trap. - .BI this "word and" that + The number register `.t' still works within diversions. *Note + Diversions::, for more information. - produces "thisword andthat" with "this" and "that" in bold face, - and "word and" in italics. + +File: groff, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps - - Macro: .IB text - Set its arguments alternately in italic and bold face, without a - space between the arguments. +5.24.3 Input Line Traps +----------------------- - - Macro: .RI text - Set its arguments alternately in roman and italic, without a space - between the arguments. + -- Request: .it n macro + -- Request: .itc n macro + Set an input line trap. N is the number of lines of input which + may be read before springing the trap, MACRO is the macro to be + invoked. Request lines are not counted as input lines. - - Macro: .IR text - Set its arguments alternately in italic and roman, without a space - between the arguments. + For example, one possible use is to have a macro which prints the + next N lines in a bold font. - - Macro: .BR text - Set its arguments alternately in bold face and roman, without a - space between the arguments. - - Macro: .RB text - Set its arguments alternately in roman and bold face, without a - space between the arguments. + .de B + . it \\$1 B-end + . ft B + .. + . + .de B-end + . ft R + .. - - Macro: .B [text] - Set TEXT in bold face. If no text is present on the line where - the macro is called, then the text of the next line appears in bold - face. + The `itc' request is identical except that an interrupted text + line (ending with `\c') is not counted as a separate line. - - Macro: .I [text] - Set TEXT in italic. If no text is present on the line where the - macro is called, then the text of the next line appears in italic. + Both requests are associated with the current environment (*note + Environments::); switching to another environment disables the + current input trap, and going back reactivates it, restoring the + number of already processed lines. -File: groff, Node: Miscellaneous man macros, Next: Predefined man strings, Prev: Man font macros, Up: man +File: groff, Node: Blank Line Traps, Next: End-of-input Traps, Prev: Input Line Traps, Up: Traps -Miscellaneous macros --------------------- +5.24.4 Blank Line Traps +----------------------- - The default indentation is 7.2n in troff mode and 7n in nroff mode -except for `grohtml' which ignores indentation. + -- Request: .blm macro + Set a blank line trap. `gtroff' executes MACRO when it encounters + a blank line in the input file. - - Macro: .DT - Set tabs every 0.5 inches. Since this macro is always executed - during a call to the `TH' macro, it makes sense to call it only if - the tab positions have been changed. + +File: groff, Node: End-of-input Traps, Prev: Blank Line Traps, Up: Traps - - Macro: .PD [nnn] - Adjust the empty space before a new paragraph (or section). The - optional argument gives the amount of space (default unit is `v'); - without parameter, the value is reset to its default value (1 line - in nroff mode, 0.4v otherwise). +5.24.5 End-of-input Traps +------------------------- - This affects the macros `SH', `SS', `TP', `LP' (as well as `PP' - and `P'), `IP', and `HP'. + -- Request: .em macro + Set a trap at the end of input. MACRO is executed after the last + line of the input file has been processed. - The following two macros are included for BSD compatibility. + 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. - - Macro: .AT [system [release]] - Alter the footer for use with AT&T manpages. This command exists - only for compatibility; don't use it. The first argument SYSTEM - can be: - `3' - 7th Edition (the default) + .de approval + . ne 5v + . sp |(\\n[.t] - 6v) + . in +4i + . lc _ + . br + Approved:\t\a + . sp + Date:\t\t\a + .. + . + .em approval - `4' - System III - `5' - System V + +File: groff, Node: Diversions, Next: Environments, Prev: Traps, Up: gtroff Reference + +5.25 Diversions +=============== + +In `gtroff' it is possible to "divert" text into a named storage area. +Due to the similarity to defining macros it is sometimes said to be +stored in a macro. This is used for saving text for output at a later +time, which is useful for keeping blocks of text on the same page, +footnotes, tables of contents, and indices. + + For orthogonality it is said that `gtroff' is in the "top-level +diversion" if no diversion is active (i.e., the data is diverted to the +output device). + + -- Request: .di macro + -- Request: .da macro + Begin a diversion. Like the `de' request, it takes an argument of + a macro name to divert subsequent text into. The `da' macro + appends to an existing diversion. + + `di' or `da' without an argument ends the diversion. + + -- Request: .box macro + -- Request: .boxa macro + Begin (or appends to) a diversion like the `di' and `da' requests. + The difference is that `box' and `boxa' do not include a + partially-filled line in the diversion. + + Compare this: + + + Before the box. + .box xxx + In the box. + .br + .box + After the box. + .br + => Before the box. After the box. + .xxx + => In the box. + + with this: + + + Before the diversion. + .di yyy + In the diversion. + .br + .di + After the diversion. + .br + => After the diversion. + .yyy + => Before the diversion. In the diversion. + + `box' or `boxa' without an argument ends the diversion. + + -- Register: \n[.z] + -- Register: \n[.d] + Diversions may be nested. The read-only number register `.z' + contains the name of the current diversion (this is a string-valued + register). The read-only number register `.d' contains the current + vertical place in the diversion. If not in a diversion it is the + same as register `nl'. + + -- Register: \n[.h] + The "high-water mark" on the current page. It corresponds to the + text baseline of the lowest line on the page. This is a read-only + register. + + + .tm .h==\n[.h], nl==\n[nl] + => .h==0, nl==-1 + This is a test. + .br + .sp 2 + .tm .h==\n[.h], nl==\n[nl] + => .h==40, nl==120 + + As can be seen in the previous example, empty lines are not + considered in the return value of the `.h' register. + + -- Register: \n[dn] + -- Register: \n[dl] + After completing a diversion, the read-write number registers `dn' + and `dl' contain the vertical and horizontal size of the diversion. + Note that only the just processed lines are counted: For the + computation of `dn' and `dl', the requests `da' and `boxa' are + handled as if `di' and `box' had been used - lines which have been + already stored in a macro are not taken into account. + + + .\" Center text both horizontally & vertically + . + .\" Enclose macro definitions in .eo and .ec + .\" to avoid the doubling of the backslash + .eo + .\" macro .(c starts centering mode + .de (c + . br + . ev (c + . evc 0 + . in 0 + . nf + . di @c + .. + + + .\" macro .)c terminates centering mode + .de )c + . br + . ev + . di + . nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v) + . sp \n[@s]u + . ce 1000 + . @c + . ce 0 + . sp \n[@s]u + . br + . fi + . rr @s + . rm @s + . rm @c + .. + .\" End of macro definitions, restore escape mechanism + .ec + + + -- Escape: \! + -- Escape: \?anything\? + Prevent requests, macros, and escapes from being interpreted when + read into a diversion. Both escapes take the given text and + "transparently" embed it into the diversion. This is useful for + macros which shouldn't be invoked until the diverted text is + actually output. + + The `\!' escape transparently embeds text up to and including the + end of the line. The `\?' escape transparently embeds text until + the next occurrence of the `\?' escape. Example: + + + \?ANYTHING\? + + ANYTHING may not contain newlines; use `\!' to embed newlines in + a diversion. The escape sequence `\?' is also recognized in copy + mode and turned into a single internal code; it is this code that + terminates ANYTHING. Thus the following example prints 4. + + + .nr x 1 + .nf + .di d + \?\\?\\\\?\\\\\\\\nx\\\\?\\?\? + .di + .nr x 2 + .di e + .d + .di + .nr x 3 + .di f + .e + .di + .nr x 4 + .f + + Both escapes read the data in copy mode. + + If `\!' is used in the top-level diversion, its argument is + directly embedded into the `gtroff' intermediate output. This can + be used for example to control a postprocessor which processes the + data before it is sent to the device driver. + + The `\?' escape used in the top-level diversion produces no output + at all; its argument is simply ignored. + + -- Request: .output string + Emit STRING directly to the `gtroff' intermediate output (subject + to copy-mode interpretation); this is similar to `\!' used at the + top level. An initial double quote in STRING is stripped off to + allow initial blanks. + + This request can't be used before the first page has started - if + you get an error, simply insert `.br' before the `output' request. + + Without argument, `output' is ignored. + + Use with caution! It is normally only needed for mark-up used by a + postprocessor which does something with the output before sending + it to the output device, filtering out STRING again. + + -- Request: .asciify div + "Unformat" the diversion specified by DIV in such a way that ASCII + characters, characters translated with the `trin' request, space + characters, and some escape sequences that were formatted and + diverted are treated like ordinary input characters when the + diversion is reread. It can be also used for gross hacks; for + example, the following sets register `n' to 1. + + + .tr @. + .di x + @nr n 1 + .br + .di + .tr @@ + .asciify x + .x + + *Note Copy-in Mode::. + + -- Request: .unformat div + Like `asciify', unformat the specified diversion. However, + `unformat' only unformats spaces and tabs between words. + Unformatted tabs are treated as input tokens, and spaces are + stretchable again. + + The vertical size of lines is not preserved; glyph information + (font, font size, space width, etc.) is retained. - An optional second argument RELEASE to `AT' specifies the release - number (such as "System V Release 3"). + +File: groff, Node: Environments, Next: Suppressing output, Prev: Diversions, Up: gtroff Reference - - Macro: .UC [version] - Alters the footer for use with BSD manpages. This command exists - only for compatibility; don't use it. The argument can be: +5.26 Environments +================= - `3' - 3rd Berkeley Distribution (the default) +It happens frequently that some text should be printed in a certain +format regardless of what may be in effect at the time, for example, in +a trap invoked macro to print headers and footers. To solve this +`gtroff' processes text in "environments". An environment contains +most of the parameters that control text processing. It is possible to +switch amongst these environments; by default `gtroff' processes text +in environment 0. The following is the information kept in an +environment. - `4' - 4th Berkeley Distribution + * font parameters (size, family, style, glyph height and slant, space + and sentence space size) - `5' - 4.2 Berkeley Distribution + * page parameters (line length, title length, vertical spacing, line + spacing, indentation, line numbering, centering, right-justifying, + underlining, hyphenation data) - `6' - 4.3 Berkeley Distribution + * fill and adjust mode - `7' - 4.4 Berkeley Distribution + * tab stops, tab and leader characters, escape character, no-break + and hyphen indicators, margin character data - -File: groff, Node: Predefined man strings, Next: Preprocessors in man pages, Prev: Miscellaneous man macros, Up: man + * partially collected lines + + * input traps + + * drawing and fill colours + + These environments may be given arbitrary names (see *Note +Identifiers::, for more info). Old versions of `troff' only had +environments named `0', `1', and `2'. + + -- Request: .ev [env] + -- Register: \n[.ev] + Switch to another environment. The argument ENV is the name of + the environment to switch to. With no argument, `gtroff' switches + back to the previous environment. There is no limit on the number + of named environments; they are created the first time that they + are referenced. The `.ev' read-only register contains the name or + number of the current environment. This is a string-valued + register. + + Note that a call to `ev' (with argument) pushes the previously + active environment onto a stack. If, say, environments `foo', + `bar', and `zap' are called (in that order), the first `ev' + request without parameter switches back to environment `bar' + (which is popped off the stack), and a second call switches back + to environment `foo'. + + Here is an example: + + + .ev footnote-env + .fam N + .ps 6 + .vs 8 + .ll -.5i + .ev + + ... -Predefined strings ------------------- + .ev footnote-env + \(dg Note the large, friendly letters. + .ev - The following strings are defined: - - String: \*[S] - Switch back to the default font size. + -- Request: .evc env + Copy the environment ENV into the current environment. - - String: \*[HF] - The typeface used for headings. The default is `B'. + The following environment data is not copied: - - String: \*[R] - The `registered' sign. + * Partially filled lines. - - String: \*[Tm] - The `trademark' sign. + * The status whether the previous line was interrupted. - - String: \*[lq] - - String: \*[rq] - Left and right quote. This is equal to `\(lq' and `\(rq', - respectively. + * The number of lines still to center, or to right-justify, or + to underline (with or without underlined spaces); they are + set to zero. + + * The status whether a temporary indentation is active. + + * Input traps and its associated data. + + * Line numbering mode is disabled; it can be reactivated with + `.nm +0'. + + * The number of consecutive hyphenated lines (set to zero). + + -- Register: \n[.w] + -- Register: \n[.cht] + -- Register: \n[.cdp] + -- Register: \n[.csk] + The `\n[.w]' register contains the width of the last glyph added + to the current environment. + + The `\n[.cht]' register contains the height of the last glyph + added to the current environment. + + The `\n[.cdp]' register contains the depth of the last glyph added + to the current environment. It is positive for glyphs extending + below the baseline. + + The `\n[.csk]' register contains the "skew" (how far to the right + of the glyph's center that `gtroff' should place an accent) of the + last glyph added to the current environment. + + -- Register: \n[.n] + The `\n[.n]' register contains the length of the previous output + line in the current environment. -File: groff, Node: Preprocessors in man pages, Next: Optional man extensions, Prev: Predefined man strings, Up: man +File: groff, Node: Suppressing output, Next: Colors, Prev: Environments, Up: gtroff Reference + +5.27 Suppressing output +======================= + + -- Escape: \Onum + Disable or enable output depending on the value of NUM: -Preprocessors in `man' pages ----------------------------- + `\O0' + Disable any glyphs from being emitted to the device driver, + provided that the escape occurs at the outer level (see + `\O[3]' and `\O[4]'). Motion is not suppressed so + effectively `\O[0]' means _pen up_. - If a preprocessor like `gtbl' or `geqn' is needed, it has become -common usage to make the first line of the man page look like this: + `\O1' + Enable output of glyphs, provided that the escape occurs at + the outer level. + `\O0' and `\O1' also reset the four registers `opminx', `opminy', + `opmaxx', and `opmaxy' to -1. *Note Register Index::. These four + registers mark the top left and bottom right hand corners of a box + which encompasses all written glyphs. - '\" WORD + For example the input text: -Note the single space character after the double quote. WORD consists -of letters for the needed preprocessors: `e' for `geqn', `r' for -`grefer', `t' for `gtbl'. Modern implementations of the `man' program -read this first line and automatically call the right preprocessor(s). + + Hello \O[0]world \O[1]this is a test. + + produces the following output: + + + Hello this is a test. + + `\O2' + Provided that the escape occurs at the outer level, enable + output of glyphs and also write out to `stderr' the page + number and four registers encompassing the glyphs previously + written since the last call to `\O'. + + `\O3' + Begin a nesting level. At start-up, `gtroff' is at outer + level. + + `\O4' + End a nesting level. + + `\O[5PFILENAME]' + This escape is `grohtml' specific. Provided that this escape + occurs at the outer nesting level write the `filename' to + `stderr'. The position of the image, P, must be specified + and must be one of `l', `r', `c', or `i' (left, right, + centered, inline). FILENAME will be associated with the + production of the next inline image. -File: groff, Node: Optional man extensions, Prev: Preprocessors in man pages, Up: man +File: groff, Node: Colors, Next: I/O, Prev: Suppressing output, Up: gtroff Reference -Optional `man' extensions -------------------------- +5.28 Colors +=========== - Use the file `man.local' for local extensions to the `man' macros or -for style changes. + -- Request: .color [n] + -- Register: \n[.color] + If N is missing or non-zero, activate colors (this is the default); + otherwise, turn it off. -Custom headers and footers -.......................... + The read-only number register `.color' is 1 if colors are active, + 0 otherwise. - In groff versions 1.18.2 and later, you can specify custom headers -and footers by redefining the following macros in `man.local'. + Internally, `color' sets a global flag; it does not produce a + token. Similar to the `cp' request, you should use it at the + beginning of your document to control color output. - - Macro: .PT - Control the content of the headers. Normally, the header prints - the command name and section number on either side, and the - optional fifth argument to `TH' in the center. + Colors can be also turned off with the `-c' command line option. - - Macro: .BT - Control the content of the footers. Normally, the footer prints - the page number and the third and fourth arguments to `TH'. + -- Request: .defcolor ident scheme color_components + Define color with name IDENT. SCHEME can be one of the following + values: `rgb' (three components), `cmy' (three components), `cmyk' + (four components), and `gray' or `grey' (one component). - Use the `FT' number register to specify the footer position. The - default is -0.5i. + Color components can be given either as a hexadecimal string or as + positive decimal integers in the range 0-65535. A hexadecimal + string contains all color components concatenated. It must start + with either `#' or `##'; the former specifies hex values in the + range 0-255 (which are internally multiplied by 257), the latter + in the range 0-65535. Examples: `#FFC0CB' (pink), `##ffff0000ffff' + (magenta). The default color name value is device-specific + (usually black). It is possible that the default color for `\m' + and `\M' is not identical. -Ultrix-specific man macros -.......................... + A new scaling indicator `f' has been introduced which multiplies + its value by 65536; this makes it convenient to specify color + components as fractions in the range 0 to 1 (1f equals 65536u). + Example: - The `groff' source distribution includes a file named `man.ultrix', -containing macros compatible with the Ultrix variant of `man'. Copy -this file into `man.local' (or use the `mso' request to load it) to -enable the following macros. - - Macro: .CT key - Print `<CTRL/KEY>'. + .defcolor darkgreen rgb 0.1f 0.5f 0.2f - - Macro: .CW - Print subsequent text using the constant width (Courier) typeface. + Note that `f' is the default scaling indicator for the `defcolor' + request, thus the above statement is equivalent to - - Macro: .Ds - Begin a non-filled display. - - Macro: .De - End a non-filled display started with `Ds'. + .defcolor darkgreen rgb 0.1 0.5 0.2 - - Macro: .EX [indent] - Begins a non-filled display using the constant width (Courier) - typeface. Use the optional INDENT argument to indent the display. - - Macro: .EE - End a non-filled display started with `EX'. + -- Request: .gcolor [color] + -- Escape: \mc + -- Escape: \m(co + -- Escape: \m[color] + -- Register: \n[.m] + Set (glyph) drawing color. The following examples show how to + turn the next four words red. - - Macro: .G [text] - Sets TEXT in Helvetica. If no text is present on the line where - the macro is called, then the text of the next line appears in - Helvetica. - - Macro: .GL [text] - Sets TEXT in Helvetica Oblique. If no text is present on the line - where the macro is called, then the text of the next line appears - in Helvetica Oblique. + .gcolor red + these are in red + .gcolor + and these words are in black. - - Macro: .HB [text] - Sets TEXT in Helvetica Bold. If no text is present on the line - where the macro is called, then all text up to the next `HB' - appears in Helvetica Bold. - - Macro: .TB [text] - Identical to `HB'. + \m[red]these are in red\m[] and these words are in black. - - Macro: .MS title sect [punct] - Set a manpage reference in Ultrix format. The TITLE is in Courier - instead of italic. Optional punctuation follows the section - number without an intervening space. + The escape `\m[]' returns to the previous color, as does a call to + `gcolor' without an argument. - - Macro: .NT [`C'] [title] - Begin a note. Print the optional title, or the word "Note", - centered on the page. Text following the macro makes up the body - of the note, and is indented on both sides. If the first argument - is `C', the body of the note is printed centered (the second - argument replaces the word "Note" if specified). + The name of the current drawing color is available in the + read-only, string-valued number register `.m'. - - Macro: .NE - End a note begun with `NT'. + The drawing color is associated with the current environment + (*note Environments::). - - Macro: .PN path [punct] - Set the path name in constant width (Courier), followed by - optional punctuation. + Note that `\m' doesn't produce an input token in `gtroff'. As a + consequence, it can be used in requests like `mc' (which expects a + single character as an argument) to change the color on the fly: - - Macro: .Pn [punct] path [punct] - When called with two arguments, identical to `PN'. When called - with three arguments, set the second argument in constant width - (Courier), bracketed by the first and third arguments in the - current font. - - Macro: .R - Switch to roman font and turn off any underlining in effect. + .mc \m[red]x\m[] - - Macro: .RN - Print the string `<RETURN>'. - - Macro: .VS [`4'] - Start printing a change bar in the margin if the number `4' is - specified. Otherwise, this macro does nothing. + -- Request: .fcolor [color] + -- Escape: \Mc + -- Escape: \M(co + -- Escape: \M[color] + -- Register: \n[.M] + Set fill (background) color for filled objects drawn with the + `\D'...'' commands. - - Macro: .VE - End printing the change bar begun by `VS'. + A red ellipse can be created with the following code: -Simple example -.............. - The following example `man.local' file alters the `SH' macro to add -some extra vertical space before printing the heading. Headings are -printed in Helvetica Bold. + \M[red]\h'0.5i'\D'E 2i 1i'\M[] + The escape `\M[]' returns to the previous fill color, as does a + call to `fcolor' without an argument. - .\" Make the heading fonts Helvetica - .ds HF HB - . - .\" Put more whitespace in front of headings. - .rn SH SH-orig - .de SH - . if t .sp (u;\\n[PD]*2) - . SH-orig \\$* - .. + The name of the current fill (background) color is available in the + read-only, string-valued number register `.M'. + + The fill color is associated with the current environment (*note + Environments::). + + Note that `\M' doesn't produce an input token in `gtroff'. -File: groff, Node: mdoc, Next: ms, Prev: man, Up: Macro Packages +File: groff, Node: I/O, Next: Postprocessor Access, Prev: Colors, Up: gtroff Reference + +5.29 I/O +======== + +`gtroff' has several requests for including files: + + -- Request: .so file + Read in the specified FILE and includes it in place of the `so' + request. This is quite useful for large documents, e.g. keeping + each chapter in a separate file. *Note gsoelim::, for more + information. + + Since `gtroff' replaces the `so' request with the contents of + `file', it makes a difference whether the data is terminated with + a newline or not: Assuming that file `xxx' contains the word `foo' + without a final newline, this + + + This is + .so xxx + bar + + yields `This is foobar'. + + The search path for FILE can be controlled with the `-I' command + line option. + + -- Request: .pso command + Read the standard output from the specified COMMAND and includes + it in place of the `pso' request. + + This request causes an error if used in safer mode (which is the + default). Use `groff''s or `troff''s `-U' option to activate + unsafe mode. + + The comment regarding a final newline for the `so' request is valid + for `pso' also. + + -- Request: .mso file + Identical to the `so' request except that `gtroff' searches for + the specified FILE in the same directories as macro files for the + the `-m' command line option. If the file name to be included has + the form `NAME.tmac' and it isn't found, `mso' tries to include + `tmac.NAME' and vice versa. + + -- Request: .trf file + -- Request: .cf file + Transparently output the contents of FILE. Each line is output as + if it were preceded by `\!'; however, the lines are not subject to + copy mode interpretation. If the file does not end with a newline, + then a newline is added (`trf' only). For example, to define a + macro `x' containing the contents of file `f', use + + + .di x + .trf f + .di + + Both `trf' and `cf', when used in a diversion, embeds an object in + the diversion which, when reread, causes the contents of FILE to + be transparently copied through to the output. In UNIX `troff', + the contents of FILE is immediately copied through to the output + regardless of whether there is a current diversion; this behaviour + is so anomalous that it must be considered a bug. + + While `cf' copies the contents of FILE completely unprocessed, + `trf' disallows characters such as NUL that are not valid `gtroff' + input characters (*note Identifiers::). + + Both requests cause a line break. + + -- Request: .nx [file] + Force `gtroff' to continue processing of the file specified as an + argument. If no argument is given, immediately jump to the end of + file. + + -- Request: .rd [prompt [arg1 arg2 ...]] + Read from standard input, and include what is read as though it + were part of the input file. Text is read until a blank line is + encountered. + + If standard input is a TTY input device (keyboard), write PROMPT + to standard error, followed by a colon (or send BEL for a beep if + no argument is given). + + Arguments after PROMPT are available for the input. For example, + the line + + + .rd data foo bar + + with the input `This is \$2.' prints + + + This is bar. + + + Using the `nx' and `rd' requests, it is easy to set up form letters. +The form letter template is constructed like this, putting the +following lines into a file called `repeat.let': + + + .ce + \*(td + .sp 2 + .nf + .rd + .sp + .rd + .fi + Body of letter. + .bp + .nx repeat.let + +When this is run, a file containing the following lines should be +redirected in. Note that requests included in this file are executed +as though they were part of the form letter. The last block of input +is the `ex' request which tells `groff' to stop processing. If this +was not there, `groff' would not know when to stop. + + + Trent A. Fisher + 708 NW 19th Av., #202 + Portland, OR 97209 + + Dear Trent, + + Len Adollar + 4315 Sierra Vista + San Diego, CA 92103 + + Dear Mr. Adollar, + + .ex + + -- Request: .pi pipe + Pipe the output of `gtroff' to the shell command(s) specified by + PIPE. This request must occur before `gtroff' has a chance to + print anything. + + `pi' causes an error if used in safer mode (which is the default). + Use `groff''s or `troff''s `-U' option to activate unsafe mode. + + Multiple calls to `pi' are allowed, acting as a chain. For + example, + + + .pi foo + .pi bar + ... -`mdoc' -====== + is the same as `.pi foo | bar'. - See the `groff_mdoc(7)' man page (type `man groff_mdoc' at the -command line). + Note that the intermediate output format of `gtroff' is piped to + the specified commands. Consequently, calling `groff' without the + `-Z' option normally causes a fatal error. + + -- Request: .sy cmds + -- Register: \n[systat] + Execute the shell command(s) specified by CMDS. The output is not + saved anyplace, so it is up to the user to do so. + + This request causes an error if used in safer mode (which is the + default). Use `groff''s or `troff''s `-U' option to activate + unsafe mode. + + For example, the following code fragment introduces the current + time into a document: + + + .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ + (localtime(time))[2,1,0]' > /tmp/x\n[$$] + .so /tmp/x\n[$$] + .sy rm /tmp/x\n[$$] + \nH:\nM:\nS + + Note that this works by having the `perl' script (run by `sy') + print out the `nr' requests which set the number registers `H', + `M', and `S', and then reads those commands in with the `so' + request. + + For most practical purposes, the number registers `seconds', + `minutes', and `hours' which are initialized at start-up of + `gtroff' should be sufficient. Use the `af' request to get a + formatted output: + + + .af hours 00 + .af minutes 00 + .af seconds 00 + \n[hours]:\n[minutes]:\n[seconds] + + The `systat' read-write number register contains the return value + of the `system()' function executed by the last `sy' request. + + -- Request: .open stream file + -- Request: .opena stream file + Open the specified FILE for writing and associates the specified + STREAM with it. + + The `opena' request is like `open', but if the file exists, append + to it instead of truncating it. + + Both `open' and `opena' cause an error if used in safer mode + (which is the default). Use `groff''s or `troff''s `-U' option to + activate unsafe mode. + + -- Request: .write stream data + -- Request: .writec stream data + Write to the file associated with the specified STREAM. The + stream must previously have been the subject of an open request. + The remainder of the line is interpreted as the `ds' request reads + its second argument: A leading `"' is stripped, and it is read in + copy-in mode. + + The `writec' request is like `write', but only `write' appends a + newline to the data. + + -- Request: .writem stream xx + Write the contents of the macro or string XX to the file + associated with the specified STREAM. + + XX is read in copy mode, i.e., already formatted elements are + ignored. Consequently, diversions must be unformatted with the + `asciify' request before calling `writem'. Usually, this means a + loss of information. + + -- Request: .close stream + Close the specified STREAM; the stream is no longer an acceptable + argument to the `write' request. + + Here a simple macro to write an index entry. + + + .open idx test.idx + . + .de IX + . write idx \\n[%] \\$* + .. + . + .IX test entry + . + .close idx + + + -- Escape: \Ve + -- Escape: \V(ev + -- Escape: \V[env] + Interpolate the contents of the specified environment variable ENV + (one-character name E, two-character name EV) as returned by the + function `getenv'. `\V' is interpreted in copy-in mode. -File: groff, Node: ms, Next: me, Prev: mdoc, Up: Macro Packages +File: groff, Node: Postprocessor Access, Next: Miscellaneous, Prev: I/O, Up: gtroff Reference -`ms' -==== +5.30 Postprocessor Access +========================= - The `-ms' macros are suitable for reports, letters, books, user -manuals, and so forth. The package provides macros for cover pages, -section headings, paragraphs, lists, footnotes, pagination, and a table -of contents. +There are two escapes which give information directly to the +postprocessor. This is particularly useful for embedding POSTSCRIPT +into the final document. -* Menu: + -- Escape: \X'xxx' + Embeds its argument into the `gtroff' output preceded with `x X'. + + The escapes `\&', `\)', `\%', and `\:' are ignored within `\X', + `\ ' and `\~' are converted to single space characters. All other + escapes (except `\\' which produces a backslash) cause an error. + + If the `use_charnames_in_special' keyword is set in the `DESC' + file, special characters no longer cause an error; the name XX is + represented as `\(XX)' in the `x X' output command. Additionally, + the backslash is represented as `\\'. -* ms Intro:: -* General ms Structure:: -* ms Document Control Registers:: -* ms Cover Page Macros:: -* ms Body Text:: -* ms Page Layout:: -* Differences from AT&T ms:: + `use_charnames_in_special' is currently used by `grohtml' only. + + -- Escape: \Yn + -- Escape: \Y(nm + -- Escape: \Y[name] + This is approximately equivalent to `\X'\*[NAME]'' (one-character + name N, two-character name NM). However, the contents of the + string or macro NAME are not interpreted; also it is permitted for + NAME to have been defined as a macro and thus contain newlines (it + is not permitted for the argument to `\X' to contain newlines). + The inclusion of newlines requires an extension to the UNIX `troff' + output format, and confuses drivers that do not know about this + extension (*note Device Control Commands::). + + *Note Output Devices::. -File: groff, Node: ms Intro, Next: General ms Structure, Prev: ms, Up: ms +File: groff, Node: Miscellaneous, Next: Gtroff Internals, Prev: Postprocessor Access, Up: gtroff Reference + +5.31 Miscellaneous +================== + +This section documents parts of `gtroff' which cannot (yet) be +categorized elsewhere in this manual. + + -- Request: .nm [start [inc [space [indent]]]] + Print line numbers. START is the line number of the _next_ output + line. INC indicates which line numbers are printed. For example, + the value 5 means to emit only line numbers which are multiples + of 5; this defaults to 1. SPACE is the space to be left between + the number and the text; this defaults to one digit space. The + fourth argument is the indentation of the line numbers, defaulting + to zero. Both SPACE and INDENT are given as multiples of digit + spaces; they can be negative also. Without any arguments, line + numbers are turned off. + + `gtroff' reserves three digit spaces for the line number (which is + printed right-justified) plus the amount given by INDENT; the + output lines are concatenated to the line numbers, separated by + SPACE, and _without_ reducing the line length. Depending on the + value of the horizontal page offset (as set with the `po' + request), line numbers which are longer than the reserved space + stick out to the left, or the whole line is moved to the right. + + Parameters corresponding to missing arguments are not changed; any + non-digit argument (to be more precise, any argument starting with + a character valid as a delimiter for identifiers) is also treated + as missing. + + If line numbering has been disabled with a call to `nm' without an + argument, it can be reactivated with `.nm +0', using the + previously active line numbering parameters. + + The parameters of `nm' are associated with the current environment + (*note Environments::). The current output line number is + available in the number register `ln'. + + + .po 1m + .ll 2i + This test shows how line numbering works with groff. + .nm 999 + This test shows how line numbering works with groff. + .br + .nm xxx 3 2 + .ll -\w'0'u + This test shows how line numbering works with groff. + .nn 2 + This test shows how line numbering works with groff. + + And here the result: + + + This test shows how + line numbering works + 999 with groff. This + 1000 test shows how line + 1001 numbering works with + 1002 groff. + This test shows how + line numbering + works with groff. + This test shows how + 1005 line numbering + works with groff. + + + -- Request: .nn [skip] + Temporarily turn off line numbering. The argument is the number + of lines not to be numbered; this defaults to 1. + + -- Request: .mc glyph [dist] + Print a "margin character" to the right of the text.(1) (*note + Miscellaneous-Footnote-1::) The first argument is the glyph to be + printed. The second argument is the distance away from the right + margin. If missing, the previously set value is used; default is + 10pt). For text lines that are too long (that is, longer than the + text length plus DIST), the margin character is directly appended + to the lines. + + With no arguments the margin character is turned off. If this + occurs before a break, no margin character is printed. + + For 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. Thus + + + .ll 1i + .mc \[br] + .mc + xxx + .br + xxx + + produces + + + xxx | + xxx + + For empty lines and lines produced by the `tl' request no margin + character is emitted. + + The margin character is associated with the current environment + (*note Environments::). + + This is quite useful for indicating text that has changed, and, in + fact, there are programs available for doing this (they are called + `nrchbar' and `changebar' and can be found in any + `comp.sources.unix' archive). + + + .ll 3i + .mc | + This paragraph is highlighted with a margin + character. + .sp + Note that vertical space isn't marked. + .br + \& + .br + But we can fake it with `\&'. + + Result: + + + This paragraph is highlighted | + with a margin character. | + + Note that vertical space isn't | + marked. | + | + But we can fake it with `\&'. | + + + -- Request: .psbb filename + -- Register: \n[llx] + -- Register: \n[lly] + -- Register: \n[urx] + -- Register: \n[ury] + Retrieve the bounding box of the PostScript image found in + FILENAME. The file must conform to Adobe's "Document Structuring + Conventions" (DSC); the command searches for a `%%BoundingBox' + comment and extracts the bounding box values into the number + registers `llx', `lly', `urx', and `ury'. If an error occurs (for + example, `psbb' cannot find the `%%BoundingBox' comment), it sets + the four number registers to zero. -Introduction to `ms' --------------------- + The search path for FILENAME can be controlled with the `-I' + command line option. - The original `-ms' macros were included with AT&T `troff' as well as -the `man' macros. While the `man' package is intended for brief -documents that can be read on-line as well as printed, the `ms' macros -are suitable for longer documents that are meant to be printed rather -than read on-line. + +File: groff, Node: Miscellaneous-Footnotes, Up: Miscellaneous - The `ms' macro package included with `groff' is a complete, -bottom-up re-implementation. Several macros (specific to AT&T or -Berkeley) are not included, while several new commands are. *Note -Differences from AT&T ms::, for more information. + (1) "Margin character" is a misnomer since it is an output glyph. -File: groff, Node: General ms Structure, Next: ms Document Control Registers, Prev: ms Intro, Up: ms +File: groff, Node: Gtroff Internals, Next: Debugging, Prev: Miscellaneous, Up: gtroff Reference + +5.32 `gtroff' Internals +======================= + +`gtroff' processes input in three steps. One or more input characters +are converted to an "input token".(1) (*note Gtroff +Internals-Footnote-1::) Then, one or more input tokens are converted +to an "output node". Finally, output nodes are converted to the +intermediate output language understood by all output devices. + + Actually, before step one happens, `gtroff' converts certain escape +sequences into reserved input characters (not accessible by the user); +such reserved characters are used for other internal processing also - +this is the very reason why not all characters are valid input. *Note +Identifiers::, for more on this topic. + + For example, the input string `fi\[:u]' is converted into a +character token `f', a character token `i', and a special token `:u' +(representing u umlaut). Later on, the character tokens `f' and `i' +are merged to a single output node representing the ligature glyph `fi' +(provided the current font has a glyph for this ligature); the same +happens with `:u'. All output glyph nodes are `processed' which means +that they are invariably associated with a given font, font size, +advance width, etc. During the formatting process, `gtroff' itself +adds various nodes to control the data flow. + + Macros, diversions, and strings collect elements in two chained +lists: a list of input tokens which have been passed unprocessed, and a +list of output nodes. Consider the following the diversion. + + + .di xxx + a + \!b + c + .br + .di + +It contains these elements. + +node list token list element number +line start node -- 1 +glyph node `a' -- 2 +word space node -- 3 +-- `b' 4 +-- `\n' 5 +glyph node `c' -- 6 +vertical size node -- 7 +vertical size node -- 8 +-- `\n' 9 + +Elements 1, 7, and 8 are inserted by `gtroff'; the latter two (which +are always present) specify the vertical extent of the last line, +possibly modified by `\x'. The `br' request finishes the current +partial line, inserting a newline input token which is subsequently +converted to a space when the diversion is reread. Note that the word +space node has a fixed width which isn't stretchable anymore. To +convert horizontal space nodes back to input tokens, use the `unformat' +request. + + Macros only contain elements in the token list (and the node list is +empty); diversions and strings can contain elements in both lists. -General structure of an `ms' document -------------------------------------- + Note that the `chop' request simply reduces the number of elements +in a macro, string, or diversion by one. Exceptions are "compatibility +save" and "compatibility ignore" input tokens which are ignored. The +`substring' request also ignores those input tokens. - The `ms' macro package expects a certain amount of structure, but -not as much as packages such as `man' or `mdoc'. + 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'. - The simplest documents can begin with a paragraph macro (such as -`LP' or `PP'), and consist of text separated by paragraph macros or -even blank lines. Longer documents have a structure as follows: -*Document type* - If you invoke the `RP' (report) macro on the first line of the - document, `groff' prints the cover page information on its own - page; otherwise it prints the information on the first page with - your document text immediately following. Other document formats - found in AT&T `troff' are specific to AT&T or Berkeley, and are - not supported in `groff'. + .fchar \[foo] foo + .tr x \[foo] -*Format and layout* - By setting number registers, you can change your document's type - (font and size), margins, spacing, headers and footers, and - footnotes. *Note ms Document Control Registers::, for more - details. +Now let us assume that we install an additional special font `bar' +which has glyph `foo'. -*Cover page* - A cover page consists of a title, the author's name and - institution, an abstract, and the date. (1) (*note General ms - Structure-Footnote-1::) *Note ms Cover Page Macros::, for more - details. -*Body* - Following the cover page is your document. You can use the `ms' - macros to write reports, letters, books, and so forth. The - package is designed for structured documents, consisting of - paragraphs interspersed with headings and augmented by lists, - footnotes, tables, and other common constructs. *Note ms Body - Text::, for more details. + .special bar + .rchar \[foo] -*Table of contents* - Longer documents usually include a table of contents, which you - can invoke by placing the `TC' macro at the end of your document. - The `ms' macros have minimal indexing facilities, consisting of the - `IX' macro, which prints an entry on standard error. Printing the - table of contents at the end is necessary since `groff' is a - single-pass text formatter, thus it cannot determine the page - number of each section until that section has actually been set - and printed. Since `ms' output is intended for hardcopy, you can - manually relocate the pages containing the table of contents - between the cover page and the body text after printing. +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 the compatibility mode: + + + .cp 1 \" switch to compatibility mode + .de xx + \\$1 + .. + .cp 0 \" switch compatibility mode off + .xx caf\['e] + => café + +Since compatibility mode is on while `de' is called, the macro `xx' +activates compatibility mode while executing. Argument `$1' can still +be handled properly because it inherits the compatibility mode status +which was active at the point where `xx' is called. + + After expansion of the parameters, the compatibility save and restore +tokens are removed. -File: groff, Node: General ms Structure-Footnotes, Up: General ms Structure +File: groff, Node: Gtroff Internals-Footnotes, Up: Gtroff Internals - (1) Actually, only the title is required. + (1) Except the escapes `\f', `\F', `\H', `\m', `\M', `\R', `\s', and +`\S' which are processed immediately if not in copy-in mode. -File: groff, Node: ms Document Control Registers, Next: ms Cover Page Macros, Prev: General ms Structure, Up: ms +File: groff, Node: Debugging, Next: Implementation Differences, Prev: Gtroff Internals, Up: gtroff Reference -Document control registers --------------------------- +5.33 Debugging +============== - The following is a list of document control number registers. For -the sake of consistency, set registers related to margins at the -beginning of your document, or just after the `RP' macro. You can set -other registers later in your document, but you should keep them -together at the beginning to make them easy to find and edit as -necessary. +`gtroff' is not easy to debug, but there are some useful features and +strategies for debugging. -Margin Settings -............... + -- Request: .lf line [filename] + Change the line number and optionally the file name `gtroff' shall + use for error and warning messages. LINE is the input line number + of the _next_ line. - - Register: \n[PO] - Defines the page offset (i.e. the left margin). There is no - explicit right margin setting; the combination of the `PO' and - `LL' registers implicitly define the right margin width. + Without argument, the request is ignored. - Effective: next page. + This is a debugging aid for documents which are split into many + files, then put together with `soelim' and other preprocessors. + Usually, it isn't invoked manually. - Default value: 1i. + Note that other `troff' implementations (including the original + AT&T version) handle `lf' differently. For them, LINE changes the + line number of the _current_ line. - - Register: \n[LL] - Defines the line length (i.e. the width of the body text). + -- Request: .tm string + -- Request: .tm1 string + -- Request: .tmc string + Send STRING to the standard error output; this is very useful for + printing debugging messages among other things. - Effective: next paragraph. + STRING is read in copy mode. - Default: 6i. + The `tm' request ignores leading spaces of STRING; `tm1' handles + its argument similar to the `ds' request: a leading double quote + in STRING is stripped to allow initial blanks. - - Register: \n[LT] - Defines the title length (i.e. the header and footer width). This - is usually the same as `LL', but not necessarily. + The `tmc' request is similar to `tm1' but does not append a + newline (as is done in `tm' and `tm1'). - Effective: next paragraph. + -- Request: .ab [string] + Similar to the `tm' request, except that it causes `gtroff' to + stop processing. With no argument it prints `User Abort.' to + standard error. - Default: 6i. + -- Request: .ex + The `ex' request also causes `gtroff' to stop processing; see also + *Note I/O::. - - Register: \n[HM] - Defines the header margin height at the top of the page. + 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. - Effective: next page. - Default: 1i. + .if \n(DB .tm debugging output - - Register: \n[FM] - Defines the footer margin height at the bottom of the page. +To activate these statements say - Effective: next page. - Default: 1i. + groff -rDB=1 file -Text Settings -............. + If it is known in advance that there will be many errors and no +useful output, `gtroff' can be forced to suppress formatted output with +the `-z' flag. - - Register: \n[PS] - Defines the point size of the body text. + -- Request: .pm + Print the entire symbol table on `stderr'. Names of all defined + macros, strings, and diversions are print together with their size + in bytes. Since `gtroff' sometimes adds nodes by itself, the + returned size can be larger than expected. - Effective: next paragraph. + This request differs from UNIX `troff': `gtroff' reports the sizes + of diversions, ignores an additional argument to print only the + total of the sizes, and the size isn't returned in blocks of 128 + characters. - Default: 10p. + -- Request: .pnr + Print the names and contents of all currently defined number + registers on `stderr'. - - Register: \n[VS] - Defines the space between lines (line height plus leading). + -- Request: .ptr + Print the names and positions of all traps (not including input + line traps and diversion traps) on `stderr'. Empty slots in the + page trap list are printed as well, because they can affect the + priority of subsequently planted traps. - Effective: next paragraph. + -- 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. - Default: 12p. + This request causes a line break. -Paragraph Settings -.................. + -- Request: .backtrace + Print a backtrace of the input stack to the standard error stream. + + Consider the following in file `test': + + + .de xxx + . backtrace + .. + .de yyy + . xxx + .. + . + .yyy - - Register: \n[PI] - Defines the initial indent of a `.PP' paragraph. + On execution, `gtroff' prints the following: - Effective: next paragraph. - Default: 5n. + test:2: backtrace: macro `xxx' + test:5: backtrace: macro `yyy' + test:8: backtrace: file `test' - - Register: \n[PD] - Defines the space between paragraphs. + The option `-b' of `gtroff' internally calls a variant of this + request on each error and warning. - Effective: next paragraph. + -- Register: \n[slimit] + Use the `slimit' number register to set the maximum number of + objects on the input stack. If `slimit' is less than or equal + to 0, there is no limit set. With no limit, a buggy recursive + macro can exhaust virtual memory. - Default: 0.3v. + The default value is 1000; this is a compile-time constant. - - Register: \n[QI] - Defines the indent on both sides of a quoted (`.QP') paragraph. + -- Request: .warnscale si + Set the scaling indicator used in warnings to SI. Valid values for + SI are `u', `i', `c', `p', and `P'. At startup, it is set to `i'. - Effective: next paragraph. + -- Request: .spreadwarn [limit] + Make `gtroff' emit a warning if the additional space inserted for + each space between words in an output line is larger or equal to + LIMIT. A negative value is changed to zero; no argument toggles + the warning on and off without changing LIMIT. The default scaling + indicator is `m'. At startup, `spreadwarn' is deactivated, and + LIMIT is set to 3m. - Default: 5n. + For example, -Footnote Settings -................. - - Register: \n[FL] - Defines the length of a footnote. + .spreadwarn 0.2m - Effective: next footnote. + will cause a warning if `gtroff' must add 0.2m or more for each + interword space in a line. - Default: `\n[LL]' * 5 / 6. + This request is active only if text is justified to both margins + (using `.ad b'). - - Register: \n[FI] - Defines the footnote indent. + `gtroff' has command line options for printing out more warnings +(`-w') and for printing backtraces (`-b') when a warning or an error +occurs. The most verbose level of warnings is `-ww'. - Effective: next footnote. + -- Request: .warn [flags] + -- Register: \n[.warn] + Control the level of warnings checked for. The FLAGS are the sum + of the numbers associated with each warning that is to be enabled; + all other warnings are disabled. The number associated with each + warning is listed below. For example, `.warn 0' disables all + warnings, and `.warn 1' disables all warnings except that about + missing glyphs. If no argument is given, all warnings are enabled. - Default: 2n. + The read-only number register `.warn' contains the current warning + level. - - Register: \n[FF] - The footnote format: - `0' - Prints the footnote number as a superscript; indents the - footnote (default). +* Menu: + +* Warnings:: - `1' - Prints the number followed by a period (like 1.) and indents - the footnote. + +File: groff, Node: Warnings, Prev: Debugging, Up: Debugging + +5.33.1 Warnings +--------------- + +The warnings that can be given to `gtroff' are divided into the +following categories. The name associated with each warning is used by +the `-w' and `-W' options; the number is used by the `warn' request and +by the `.warn' register. + +`char' +`1' + Non-existent glyphs.(1) (*note Warnings-Footnote-1::) This is + enabled by default. + +`number' +`2' + Invalid numeric expressions. This is enabled by default. *Note + Expressions::. + +`break' +`4' + In fill mode, lines which could not be broken so that their length + was less than the line length. This is enabled by default. + +`delim' +`8' + Missing or mismatched closing delimiters. + +`el' +`16' + Use of the `el' request with no matching `ie' request. *Note + if-else::. + +`scale' +`32' + Meaningless scaling indicators. + +`range' +`64' + Out of range arguments. + +`syntax' +`128' + Dubious syntax in numeric expressions. + +`di' +`256' + Use of `di' or `da' without an argument when there is no current + diversion. + +`mac' +`512' + Use of undefined strings, macros and diversions. When an undefined + string, macro, or diversion is used, that string is automatically + defined as empty. So, in most cases, at most one warning is given + for each name. + +`reg' +`1024' + Use of undefined number registers. When an undefined number + register is used, that register is automatically defined to have a + value of 0. So, in most cases, at most one warning is given for + use of a particular name. + +`tab' +`2048' + Use of a tab character where a number was expected. + +`right-brace' +`4096' + Use of `\}' where a number was expected. + +`missing' +`8192' + Requests that are missing non-optional arguments. + +`input' +`16384' + Invalid input characters. + +`escape' +`32768' + Unrecognized escape sequences. When an unrecognized escape + sequence `\X' is encountered, the escape character is ignored, and + X is printed. + +`space' +`65536' + Missing space between a request or macro and its argument. This + warning is given when an undefined name longer than two characters + is encountered, and the first two characters of the name make a + defined name. The request or macro is not invoked. When this + warning is given, no macro is automatically defined. This is + enabled by default. This warning never occurs in compatibility + mode. + +`font' +`131072' + Non-existent fonts. This is enabled by default. + +`ig' +`262144' + Invalid escapes in text ignored with the `ig' request. These are + conditions that are errors when they do not occur in ignored text. + +`color' +`524288' + Color related warnings. + +`all' + All warnings except `di', `mac' and `reg'. It is intended that + this covers all warnings that are useful with traditional macro + packages. + +`w' + All warnings. - `2' - Like 1, without an indent. + +File: groff, Node: Warnings-Footnotes, Up: Warnings - `3' - Like 1, but prints the footnote number as a hanging paragraph. + (1) `char' is a misnomer since it reports missing glyphs - there +aren't missing input characters, only invalid ones. - Effective: next footnote. + +File: groff, Node: Implementation Differences, Prev: Debugging, Up: gtroff Reference - Default: 0. +5.34 Implementation Differences +=============================== -Miscellaneous Number Registers -.............................. +GNU `troff' has a number of features which cause incompatibilities with +documents written with old versions of `troff'. - - Register: \n[MINGW] - Defines the minimum width between columns in a multi-column - document. + Long names cause some incompatibilities. UNIX `troff' interprets + + + .dsabcd + +as defining a string `ab' with contents `cd'. Normally, GNU `troff' +interprets this as a call of a macro named `dsabcd'. Also UNIX `troff' +interprets `\*[' or `\n[' as references to a string or number register +called `['. In GNU `troff', however, this is normally interpreted as +the start of a long name. In compatibility mode GNU `troff' interprets +long names in the traditional way (which means that they are not +recognized as names). + + -- Request: .cp [n] + -- Request: .do cmd + -- Register: \n[.C] + If N is missing or non-zero, turn on compatibility mode; + otherwise, turn it off. + + The read-only number register `.C' is 1 if compatibility mode is + on, 0 otherwise. + + Compatibility mode can be also turned on with the `-C' command line + option. - Effective: next page. + The `do' request turns off compatibility mode while executing its + arguments as a `gtroff' command. - Default: 2n. + + .do fam T + + executes the `fam' request when compatibility mode is enabled. + + `gtroff' restores the previous compatibility setting before + interpreting any files sourced by the CMD. + + Two other features are controlled by `-C'. If not in compatibility +mode, GNU `troff' preserves the input level in delimited arguments: + + + .ds xx ' + \w'abc\*(xxdef' + +In compatibility mode, the string `72def'' is returned; without `-C' +the resulting string is `168' (assuming a TTY output device). + + Finally, the escapes `\f', `\H', `\m', `\M', `\R', `\s', and `\S' +are transparent for recognizing the beginning of a line only in +compatibility mode (this is a rather obscure feature). For example, +the code + + + .de xx + Hallo! + .. + \fB.xx\fP + +prints `Hallo!' in bold face if in compatibility mode, and `.xx' in +bold face otherwise. + + GNU `troff' does not allow the use of the escape sequences `\|', +`\^', `\&', `\{', `\}', `\<SP>', `\'', `\`', `\-', `\_', `\!', `\%', +and `\c' in names of strings, macros, diversions, number registers, +fonts or environments; UNIX `troff' does. The `\A' escape sequence +(*note Identifiers::) may be helpful in avoiding use of these escape +sequences in names. + + Fractional point sizes cause one noteworthy incompatibility. In +UNIX `troff' the `ps' request ignores scale indicators and thus + + + .ps 10u + +sets the point size to 10 points, whereas in GNU `troff' it sets the +point size to 10 scaled points. *Note Fractional Type Sizes::, for +more information. + + In GNU `troff' there is a fundamental difference between +(unformatted) input characters and (formatted) output glyphs. +Everything that affects how a glyph is output is stored with the glyph +node; once a glyph node has been constructed it is unaffected by any +subsequent requests that are executed, including `bd', `cs', `tkf', +`tr', or `fp' requests. Normally glyphs are constructed from input +characters at the moment immediately before the glyph is added to the +current output line. Macros, diversions and strings are all, in fact, +the same type of object; they contain lists of input characters and +glyph nodes in any combination. A glyph node does not behave like an +input character for the purposes of macro processing; it does not +inherit any of the special properties that the input character from +which it was constructed might have had. For example, + + + .di x + \\\\ + .br + .di + .x + +prints `\\' in GNU `troff'; each pair of input backslashes is turned +into one output backslash and the resulting output backslashes are not +interpreted as escape characters when they are reread. UNIX `troff' +would interpret them as escape characters when they were reread and +would end up printing one `\'. The correct way to obtain a printable +backslash is to use the `\e' escape sequence: This always prints a +single instance of the current escape character, regardless of whether +or not it is used in a diversion; it also works in both GNU `troff' and +UNIX `troff'.(1) (*note Implementation Differences-Footnote-1::) To +store, for some reason, an escape sequence in a diversion that will be +interpreted when the diversion is reread, either use the traditional +`\!' transparent output facility, or, if this is unsuitable, the new +`\?' escape sequence. + + *Note Diversions::, and *Note Gtroff Internals::, for more +information. + + +File: groff, Node: Implementation Differences-Footnotes, Up: Implementation Differences + + (1) To be completely independent of the current escape character, +use `\(rs' which represents a reverse solidus (backslash) glyph. -File: groff, Node: ms Cover Page Macros, Next: ms Body Text, Prev: ms Document Control Registers, Up: ms +File: groff, Node: Preprocessors, Next: Output Devices, Prev: gtroff Reference, Up: Top -Cover page macros ------------------ +6 Preprocessors +*************** - Use the following macros to create a cover page for your document in -the order shown. +This chapter describes all preprocessors that come with `groff' or +which are freely available. - - Macro: .RP [`no'] - Specifies the report format for your document. The report format - creates a separate cover page. The default action (no `.RP' - macro) is to print a subset of the cover page on page 1 of your - document. +* Menu: - If you use the word `no' as an optional argument, `groff' prints a - title page but does not repeat any of the title page information - (title, author, abstract, etc.) on page 1 of the document. - - - Macro: .DA [...] - (optional) Print the current date, or the arguments to the macro - if any, on the title page (if specified) and in the footers. This - is the default for `nroff'. - - - Macro: .ND [...] - (optional) Print the current date, or the arguments to the macro - if any, on the title page (if specified) but not in the footers. - This is the default for `troff'. - - - Macro: .TL - Specifies the document title. `groff' collects text following the - `.TL' macro into the title, until reaching the author name or - abstract. - - - Macro: .AU - Specifies the author's name, which appears on the line (or lines) - immediately following. You can specify multiple authors as - follows: - - - .AU - John Doe - .AI - University of West Bumblefuzz - .AU - Martha Buck - .AI - Monolithic Corporation - - ... +* geqn:: +* gtbl:: +* gpic:: +* ggrn:: +* grap:: +* grefer:: +* gsoelim:: + +File: groff, Node: geqn, Next: gtbl, Prev: Preprocessors, Up: Preprocessors - - Macro: .AI - Specifies the author's institution. You can specify multiple - institutions in the same way that you specify multiple authors. - - - Macro: .AB [`no'] - Begins the abstract. The default is to print the word ABSTRACT, - centered and in italics, above the text of the abstract. The word - `no' as an optional argument suppresses this heading. - - - Macro: .AE - End the abstract. - - The following is example mark-up for a title page. - - - .RP - .TL - The Inevitability of Code Bloat - in Commercial and Free Software - .AU - J. Random Luser - .AI - University of West Bumblefuzz - .AB - This report examines the long-term growth - of the code bases in two large, popular software - packages; the free Emacs and the commercial - Microsoft Word. - While differences appear in the type or order - of features added, due to the different - methodologies used, the results are the same - in the end. - .PP - The free software approach is shown to be - superior in that while free software can - become as bloated as commercial offerings, - free software tends to have fewer serious - bugs and the added features are in line with - user demand. - .AE - - ... the rest of the paper follows ... - - -File: groff, Node: ms Body Text, Next: ms Page Layout, Prev: ms Cover Page Macros, Up: ms - -Body text ---------- - - This section describes macros used to mark up the body of your -document. Examples include paragraphs, sections, and other groups. +6.1 `geqn' +========== * Menu: -* Paragraphs in ms:: -* Headings in ms:: -* Highlighting in ms:: -* Lists in ms:: -* Indents in ms:: -* Tabstops in ms:: -* ms Displays and Keeps:: -* ms Insertions:: -* Example multi-page table:: -* ms Footnotes:: +* Invoking geqn:: -File: groff, Node: Paragraphs in ms, Next: Headings in ms, Prev: ms Body Text, Up: ms Body Text +File: groff, Node: Invoking geqn, Prev: geqn, Up: geqn -Paragraphs -.......... +6.1.1 Invoking `geqn' +--------------------- - The following paragraph types are available. + +File: groff, Node: gtbl, Next: gpic, Prev: geqn, Up: Preprocessors - - Macro: .PP - Sets a paragraph with an initial indent. +6.2 `gtbl' +========== - - Macro: .LP - Sets a paragraph with no initial indent. +* Menu: - - Macro: .QP - Sets a paragraph that is indented at both left and right margins. - The effect is identical to the HTML `<BLOCKQUOTE>' element. The - next paragraph or heading returns margins to normal. +* Invoking gtbl:: - - Macro: .XP - Sets a paragraph whose lines are indented, except for the first - line. This is a Berkeley extension. + +File: groff, Node: Invoking gtbl, Prev: gtbl, Up: gtbl - The following markup uses all four paragraph macros. +6.2.1 Invoking `gtbl' +--------------------- + +File: groff, Node: gpic, Next: ggrn, Prev: gtbl, Up: Preprocessors - .NH 2 - Cases used in the study - .LP - The following software and versions were - considered for this report. - .PP - For commercial software, we chose - .B "Microsoft Word for Windows" , - starting with version 1.0 through the - current version (Word 2000). - .PP - For free software, we chose - .B Emacs , - from its first appearance as a standalone - editor through the current version (v20). - See [Bloggs 2002] for details. - .QP - Franklin's Law applied to software: - software expands to outgrow both - RAM and disk space over time. - .LP - Bibliography: - .XP - Bloggs, Joseph R., - .I "Everyone's a Critic" , - Underground Press, March 2002. - A definitive work that answers all questions - and criticisms about the quality and usability of - free software. +6.3 `gpic' +========== + +* Menu: + +* Invoking gpic:: -File: groff, Node: Headings in ms, Next: Highlighting in ms, Prev: Paragraphs in ms, Up: ms Body Text +File: groff, Node: Invoking gpic, Prev: gpic, Up: gpic + +6.3.1 Invoking `gpic' +--------------------- -Headings -........ + +File: groff, Node: ggrn, Next: grap, Prev: gpic, Up: Preprocessors - Use headings to create a hierarchical structure for your document. -The `ms' macros print headings in *bold*, using the same font family -and point size as the body text. +6.4 `ggrn' +========== - The following describes the heading macros: +* Menu: - - Macro: .NH curr-level - - Macro: .NH S level0 ... - Numbered heading. The argument is either a numeric argument to - indicate the level of the heading, or the letter `S' followed by - numeric arguments to set the heading level explicitly. +* Invoking ggrn:: - If you specify heading levels out of sequence, such as invoking - `.NH 3' after `.NH 1', `groff' prints a warning on standard error. + +File: groff, Node: Invoking ggrn, Prev: ggrn, Up: ggrn - - Macro: .SH - Unnumbered subheading. +6.4.1 Invoking `ggrn' +--------------------- -File: groff, Node: Highlighting in ms, Next: Lists in ms, Prev: Headings in ms, Up: ms Body Text +File: groff, Node: grap, Next: grefer, Prev: ggrn, Up: Preprocessors -Highlighting -............ +6.5 `grap' +========== - The `ms' macros provide a variety of methods to highlight or -emphasize text: +A free implementation of `grap', written by Ted Faber, is available as +an extra package from the following address: - - Macro: .B [txt [post [pre]]] - Sets its first argument in *bold type*. If you specify a second - argument, `groff' prints it in the previous font after the bold - text, with no intervening space (this allows you to set - punctuation after the highlighted text without highlighting the - punctuation). Similarly, it prints the third argument (if any) in - the previous font *before* the first argument. For example, + `http://www.lunabase.org/~faber/Vault/software/grap/' + +File: groff, Node: grefer, Next: gsoelim, Prev: grap, Up: Preprocessors - .B foo ) ( +6.6 `grefer' +============ - prints (*foo*). +* Menu: - If you give this macro no arguments, `groff' prints all text - following in bold until the next highlighting, paragraph, or - heading macro. +* Invoking grefer:: - - Macro: .R [txt [post [pre]]] - Sets its first argument in roman (or regular) type. It operates - similarly to the `B' macro otherwise. + +File: groff, Node: Invoking grefer, Prev: grefer, Up: grefer - - Macro: .I [txt [post [pre]]] - Sets its first argument in _italic type_. It operates similarly - to the `B' macro otherwise. +6.6.1 Invoking `grefer' +----------------------- - - Macro: .CW [txt [post [pre]]] - Sets its first argument in a `constant width face'. It operates - similarly to the `B' macro otherwise. + +File: groff, Node: gsoelim, Prev: grefer, Up: Preprocessors - - Macro: .BI [txt [post [pre]]] - Sets its first argument in bold italic type. It operates - similarly to the `B' macro otherwise. +6.7 `gsoelim' +============= - - Macro: .BX [txt] - Prints its argument and draws a box around it. If you want to box - a string that contains spaces, use a digit-width space (`\0'). +* Menu: - - Macro: .UL [txt [post]] - Prints its first argument with an underline. If you specify a - second argument, `groff' prints it in the previous font after the - underlined text, with no intervening space. +* Invoking gsoelim:: - - Macro: .LG - Prints all text following in larger type (two points larger than - the current point size) until the next font size, highlighting, - paragraph, or heading macro. You can specify this macro multiple - times to enlarge the point size as needed. + +File: groff, Node: Invoking gsoelim, Prev: gsoelim, Up: gsoelim - - Macro: .SM - Prints all text following in smaller type (two points smaller than - the current point size) until the next type size, highlighting, - paragraph, or heading macro. You can specify this macro multiple - times to reduce the point size as needed. +6.7.1 Invoking `gsoelim' +------------------------ - - Macro: .NL - Prints all text following in the normal point size (that is, the - value of the `PS' register). + +File: groff, Node: Output Devices, Next: File formats, Prev: Preprocessors, Up: Top + +7 Output Devices +**************** + +* Menu: + +* Special Characters:: +* grotty:: +* grops:: +* grodvi:: +* grolj4:: +* grolbp:: +* grohtml:: +* gxditview:: -File: groff, Node: Lists in ms, Next: Indents in ms, Prev: Highlighting in ms, Up: ms Body Text +File: groff, Node: Special Characters, Next: grotty, Prev: Output Devices, Up: Output Devices -Lists -..... +7.1 Special Characters +====================== - The `.IP' macro handles duties for all lists. +*Note Font Files::. - - Macro: .IP [marker [width]] - The MARKER is usually a bullet glyph (`\[bu]') for unordered - lists, a number (or auto-incrementing number register) for - numbered lists, or a word or phrase for indented (glossary-style) - lists. + +File: groff, Node: grotty, Next: grops, Prev: Special Characters, Up: Output Devices - The WIDTH specifies the indent for the body of each list item; its - default unit is `n'. Once specified, the indent remains the same - for all list items in the document until specified again. +7.2 `grotty' +============ - The following is an example of a bulleted list. +* Menu: +* Invoking grotty:: - A bulleted list: - .IP \[bu] 2 - lawyers - .IP \[bu] - guns - .IP \[bu] - money + +File: groff, Node: Invoking grotty, Prev: grotty, Up: grotty - Produces: +7.2.1 Invoking `grotty' +----------------------- + +File: groff, Node: grops, Next: grodvi, Prev: grotty, Up: Output Devices - A bulleted list: - - o lawyers - - o guns - - o money +7.3 `grops' +=========== +* Menu: - The following is an example of a numbered list. +* Invoking grops:: +* Embedding PostScript:: + +File: groff, Node: Invoking grops, Next: Embedding PostScript, Prev: grops, Up: grops - .nr step 1 1 - A numbered list: - .IP \n[step] 3 - lawyers - .IP \n+[step] - guns - .IP \n+[step] - money +7.3.1 Invoking `grops' +---------------------- - Produces: + +File: groff, Node: Embedding PostScript, Prev: Invoking grops, Up: grops +7.3.2 Embedding POSTSCRIPT +-------------------------- - A numbered list: - - 1. lawyers - - 2. guns - - 3. money + +File: groff, Node: grodvi, Next: grolj4, Prev: grops, Up: Output Devices - Note the use of the auto-incrementing number register in this -example. +7.4 `grodvi' +============ +* Menu: - The following is an example of a glossary-style list. +* Invoking grodvi:: + +File: groff, Node: Invoking grodvi, Prev: grodvi, Up: grodvi - A glossary-style list: - .IP lawyers 0.4i - Two or more attorneys. - .IP guns - Firearms, preferably - large-caliber. - .IP money - Gotta pay for those - lawyers and guns! +7.4.1 Invoking `grodvi' +----------------------- - Produces: + +File: groff, Node: grolj4, Next: grolbp, Prev: grodvi, Up: Output Devices +7.5 `grolj4' +============ - A glossary-style list: - - lawyers - Two or more attorneys. - - guns Firearms, preferably large-caliber. - - money - Gotta pay for those lawyers and guns! +* Menu: - In the last example, the `IP' macro places the definition on the -same line as the term if it has enough space; otherwise, it breaks to -the next line and starts the definition below the term. This may or -may not be the effect you want, especially if some of the definitions -break and some do not. The following examples show two possible ways -to force a break. +* Invoking grolj4:: - The first workaround uses the `br' request to force a break after -printing the term or label. + +File: groff, Node: Invoking grolj4, Prev: grolj4, Up: grolj4 +7.5.1 Invoking `grolj4' +----------------------- - A glossary-style list: - .IP lawyers 0.4i - Two or more attorneys. - .IP guns - .br - Firearms, preferably large-caliber. - .IP money - Gotta pay for those lawyers and guns! + +File: groff, Node: grolbp, Next: grohtml, Prev: grolj4, Up: Output Devices + +7.6 `grolbp' +============ + +* Menu: + +* Invoking grolbp:: + + +File: groff, Node: Invoking grolbp, Prev: grolbp, Up: grolbp + +7.6.1 Invoking `grolbp' +----------------------- + + +File: groff, Node: grohtml, Next: gxditview, Prev: grolbp, Up: Output Devices + +7.7 `grohtml' +============= + +* Menu: +* Invoking grohtml:: +* grohtml specific registers and strings:: - The second workaround uses the `\p' escape to force the break. Note -the space following the escape; this is important. If you omit the -space, `groff' prints the first word on the same line as the term or -label (if it fits) *then* breaks the line. + +File: groff, Node: Invoking grohtml, Next: grohtml specific registers and strings, Prev: grohtml, Up: grohtml + +7.7.1 Invoking `grohtml' +------------------------ + +File: groff, Node: grohtml specific registers and strings, Prev: Invoking grohtml, Up: grohtml - A glossary-style list: - .IP lawyers 0.4i - Two or more attorneys. - .IP guns - \p Firearms, preferably large-caliber. - .IP money - Gotta pay for those lawyers and guns! +7.7.2 `grohtml' specific registers and strings +---------------------------------------------- + -- Register: \n[ps4html] + -- String: \*[www-image-template] + The registers `ps4html' and `www-image-template' are defined by + the `pre-grohtml' preprocessor. `pre-grohtml' reads in the + `troff' input, marks up the inline equations and passes the result + firstly to - To set nested lists, use the `RS' and `RE' macros. *Note Indents in -ms::, for more information. - For example: + troff -Tps -rps4html=1 -dwww-image-template=TEMPLATE + and secondly to - .IP \[bu] 2 - Lawyers: - .RS - .IP \[bu] - Dewey, - .IP \[bu] - Cheatham, - .IP \[bu] - and Howe. - .RE - .IP \[bu] - Guns - Produces: + troff -Thtml + The PostScript device is used to create all the image files, and + the register `ps4html' enables the macro sets to ignore floating + keeps, footers, and headings. - o Lawyers: - - o Dewey, - - o Cheatham, - - o and Howe. - - o Guns + The register `www-image-template' is set to the user specified + template name or the default name. -File: groff, Node: Indents in ms, Next: Tabstops in ms, Prev: Lists in ms, Up: ms Body Text +File: groff, Node: gxditview, Prev: grohtml, Up: Output Devices -Indents -....... +7.8 `gxditview' +=============== - In many situations, you may need to indent a section of text while -still wrapping and filling. *Note Lists in ms::, for an example of -nested lists. +* Menu: + +* Invoking gxditview:: - - Macro: .RS - - Macro: .RE - These macros begin and end an indented section. The `PI' register - controls the amount of indent, allowing the indented text to line - up under hanging and indented paragraphs. + +File: groff, Node: Invoking gxditview, Prev: gxditview, Up: gxditview - *Note ms Displays and Keeps::, for macros to indent and turn off -filling. +7.8.1 Invoking `gxditview' +-------------------------- -File: groff, Node: Tabstops in ms, Next: ms Displays and Keeps, Prev: Indents in ms, Up: ms Body Text +File: groff, Node: File formats, Next: Installation, Prev: Output Devices, Up: Top + +8 File formats +************** -Tab Stops -......... +All files read and written by `gtroff' are text files. The following +two sections describe their format. - Use the `ta' request to define tab stops as needed. *Note Tabs and -Fields::. +* Menu: - - Macro: .TA - Use this macro to reset the tab stops to the default for `ms' - (every 5n). You can redefine the `TA' macro to create a different - set of default tab stops. +* gtroff Output:: +* Font Files:: -File: groff, Node: ms Displays and Keeps, Next: ms Insertions, Prev: Tabstops in ms, Up: ms Body Text +File: groff, Node: gtroff Output, Next: Font Files, Prev: File formats, Up: File formats + +8.1 `gtroff' Output +=================== + +This section describes the intermediate output format of GNU `troff'. +This output is produced by a run of `gtroff' before it is fed into a +device postprocessor program. + + As `groff' is a wrapper program around `gtroff' that automatically +calls a 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 like calling `gtroff' manually. + + Here, the term "troff output" describes what is output by `gtroff', +while "intermediate output" refers to the language that is accepted by +the parser that prepares this output for the postprocessors. This +parser is smarter on whitespace 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:: -Displays and keeps + +File: groff, 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, Node: Language Concepts, Next: Command Reference, Prev: gtroff Output, Up: gtroff Output + +8.1.1 Language Concepts +----------------------- + +During the run of `gtroff', the input data is cracked down to the +information on what has to be printed at what position on the intended +device. So the language of the intermediate output format can be quite +small. Its only elements are commands with and without arguments. In +this section, the term "command" always refers to the intermediate +output language, and never to the `gtroff' language used for document +formatting. There are commands for positioning and text writing, for +drawing, and for device controlling. + +* Menu: + +* Separation:: +* Argument Units:: +* Document Parts:: + + +File: groff, Node: Separation, Next: Argument Units, Prev: Language Concepts, Up: Language Concepts + +8.1.1.1 Separation .................. - Use displays to show text-based examples or figures (such as code -listings). - - Displays turn off filling, so lines of code are displayed as-is -without inserting `br' requests in between each line. Displays can be -"kept" on a single page, or allowed to break across pages. - - - Macro: .DS L - - Macro: .LD - - Macro: .DE - Left-justified display. The `.DS L' call generates a page break, - if necessary, to keep the entire display on one page. The `LD' - macro allows the display to break across pages. The `DE' macro - ends the display. - - - Macro: .DS I - - Macro: .ID - - Macro: .DE - Indents the display as defined by the `DI' register. The `.DS I' - call generates a page break, if necessary, to keep the entire - display on one page. The `ID' macro allows the display to break - across pages. The `DE' macro ends the display. - - - Macro: .DS B - - Macro: .BD - - Macro: .DE - Sets a block-centered display: the entire display is - left-justified, but indented so that the longest line in the - display is centered on the page. The `.DS B' call generates a - page break, if necessary, to keep the entire display on one page. - The `BD' macro allows the display to break across pages. The `DE' - macro ends the display. - - - Macro: .DS C - - Macro: .CD - - Macro: .DE - Sets a centered display: each line in the display is centered. - The `.DS C' call generates a page break, if necessary, to keep the - entire display on one page. The `CD' macro allows the display to - break across pages. The `DE' macro ends the display. - - - Macro: .DS R - - Macro: .RD - - Macro: .DE - Right-justifies each line in the display. The `.DS R' call - generates a page break, if necessary, to keep the entire display - on one page. The `RD' macro allows the display to break across - pages. The `DE' macro ends the display. - - - On occasion, you may want to "keep" other text together on a page. -For example, you may want to keep two paragraphs together, or a -paragraph that refers to a table (or list, or other item) immediately -following. The `ms' macros provide the `KS' and `KE' macros for this -purpose. - - - Macro: .KS - - Macro: .KE - The `KS' macro begins a block of text to be kept on a single page, - and the `KE' macro ends the block. - - - Macro: .KF - - Macro: .KE - Specifies a "floating keep"; if the keep cannot fit on the current - page, `groff' holds the contents of the keep and allows text - following the keep (in the source file) to fill in the remainder of - the current page. When the page breaks, whether by an explicit - `bp' request or by reaching the end of the page, `groff' prints - the floating keep at the top of the new page. This is useful for - printing large graphics or tables that do not need to appear - exactly where specified. - - You can also use the `ne' request to force a page break if there is -not enough vertical space remaining on the page. - - - Use the following macros to draw a box around a section of text -(such as a display). - - - Macro: .B1 - - Macro: .B2 - Marks the beginning and ending of text that is to have a box drawn - around it. The `B1' macro begins the box; the `B2' macro ends it. - Text in the box is automatically placed in a diversion (keep). - - -File: groff, Node: ms Insertions, Next: Example multi-page table, Prev: ms Displays and Keeps, Up: ms Body Text - -Tables, figures, equations, and references -.......................................... - - The `ms' macros support the standard `groff' preprocessors: `tbl', -`pic', `eqn', and `refer'. You mark text meant for preprocessors by -enclosing it in pairs of tags as follows. - - - Macro: .TS [`H'] - - Macro: .TE - Denotes a table, to be processed by the `tbl' preprocessor. The - optional argument `H' to `TS' instructs `groff' to create a - running header with the information up to the `TH' macro. `groff' - prints the header at the beginning of the table; if the table runs - onto another page, `groff' prints the header on the next page as - well. - - - Macro: .PS - - Macro: .PE - Denotes a graphic, to be processed by the `pic' preprocessor. You - can create a `pic' file by hand, using the AT&T `pic' manual - available on the Web as a reference, or by using a graphics - program such as `xfig'. - - - Macro: .EQ [align] - - Macro: .EN - Denotes an equation, to be processed by the `eqn' preprocessor. - The optional ALIGN argument can be `C', `L', or `I' to center (the - default), left-justify, or indent the equation. - - - Macro: .[ - - Macro: .] - Denotes a reference, to be processed by the `refer' preprocessor. - The GNU `refer(1)' man page provides a comprehensive reference to - the preprocessor and the format of the bibliographic database. +AT&T `troff' output has strange requirements on whitespace. The +`gtroff' output parser, however, is smart about whitespace by making it +maximally optional. The whitespace characters, i.e., the tab, space, +and newline characters, 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 to stack 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 stretch +over several lines; all other commands must have all of their arguments +on the same line as the command, i.e., the arguments may not be +splitted 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, Node: Argument Units, Next: Document Parts, Prev: Separation, Up: Language Concepts + +8.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 +scale indicator is not written with the output command arguments. Most +commands assume the scale indicator `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. + + Note that 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 +will always be 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, Node: Document Parts, Prev: Argument Units, Up: Language Concepts + +8.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::. +Note that the parser for the intermediate output format is able to +swallow 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, Node: Command Reference, Next: Intermediate Output Examples, Prev: Language Concepts, Up: gtroff Output + +8.1.2 Command Reference +----------------------- + +This section describes all intermediate output commands, both from AT&T +`troff' as well as the `gtroff' extensions. * Menu: -* Example multi-page table:: +* Comment Command:: +* Simple Commands:: +* Graphics Commands:: +* Device Control Commands:: +* Obsolete Command:: -File: groff, Node: Example multi-page table, Next: ms Footnotes, Prev: ms Insertions, Up: ms Body Text +File: groff, Node: Comment Command, Next: Simple Commands, Prev: Command Reference, Up: Command Reference -An example multi-page table -........................... +8.1.2.1 Comment Command +....................... - The following is an example of how to set up a table that may print -across two or more pages. +`#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. - .TS H - allbox expand; - cb | cb . - Text ...of heading... - _ - .TH - .T& - l | l . - ... the rest of the table follows... - .CW - .TE + +File: groff, Node: Simple Commands, Next: Graphics Commands, Prev: Comment Command, Up: Command Reference + +8.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 smart +about 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 only necessary when two +integer arguments would clash or if the preceding argument ends with a +string argument. + +`C XXX<whitespace>' + Print a special character named XXX. The trailing syntactical + space or line break is necessary to allow glyph names of arbitrary + length. The glyph is printed at the current print position; the + glyph's size is read from the font file. The print position is + not changed. + +`c G' + Print glyph G at the current print position;(1) (*note Simple + Commands-Footnote-1::) the glyph's size is read from the font + file. The print position is not changed. + +`f N' + Set font to font number N (a non-negative integer). + +`H N' + Move right to the absolute vertical position N (a non-negative + integer in basic units `u' relative to left edge of current page. + +`h N' + Move N (a non-negative integer) basic units `u' horizontally to + the right. The original UNIX troff manual allows negative values + for N also, but `gtroff' doesn't use this. + +`m COLOR-SCHEME [COMPONENT ...]' + Set the color for text (glyphs), line drawing, and the outline of + graphic objects using different color schemes; the analoguous + command for the filling color of graphic objects is `DF'. The + color components are specified as integer arguments between 0 and + 65536. The number of color components and their meaning vary for + the different color schemes. These commands are generated by + `gtroff''s escape sequence `\m'. No position changing. These + commands are a `gtroff' extension. + + `mc CYAN MAGENTA YELLOW' + Set color using the CMY color scheme, having the 3 color + components CYAN, MAGENTA, and YELLOW. + + `md' + Set color to the default color value (black in most cases). + No component arguments. + + `mg GRAY' + Set color to the shade of gray given by the argument, an + integer between 0 (black) and 65536 (white). + + `mk CYAN MAGENTA YELLOW BLACK' + Set color using the CMYK color scheme, having the 4 color + components CYAN, MAGENTA, YELLOW, and BLACK. + + `mr RED GREEN BLUE' + Set color using the RGB color scheme, having the 3 color + components RED, GREEN, and BLUE. + +`N N' + Print glyph with index N (a non-negative integer) of the current + font. This command is a `gtroff' extension. + +`n B A' + Inform the device about a line break, but no positioning is done by + this command. In AT&T `troff', the integer arguments B and A + informed about the space before and after the current line to make + the intermediate output more human readable without performing any + action. In `groff', they are just ignored, but they must be + provided for compatibility reasons. + +`p N' + Begin a new page in the outprint. The page number is set to N. + This page is completely independent of pages formerly processed + even if those have the same page number. The vertical position on + the outprint is automatically set to 0. All positioning, writing, + and drawing is always done relative to a page, so a `p' command + must be issued before any of these commands. + +`s N' + Set point size to N scaled points (this is unit `z'). AT&T + `troff' used the unit points (`p') instead. *Note Output Language + Compatibility::. + +`t XXX<whitespace>' +`t XXX DUMMY-ARG<whitespace>' + Print a word, i.e., a sequence of characters XXX representing + output glyphs which names are single characters, 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). The first glyph should be printed at the + current position, the current horizontal position should then be + increased by the width of the first glyph, and so on for each + glyph. The widths of the glyphs are read from the font file, + scaled for the current point size, and rounded to a multiple of + the horizontal resolution. Special characters cannot be printed + using this command (use the `C' command for special characters). + This command is a `gtroff' extension; it is only used for devices + whose `DESC' file contains the `tcommand' keyword (*note DESC File + Format::). + +`u N XXX<whitespace>' + Print word with track kerning. This is the same as the `t' + command except that after printing each glyph, the current + horizontal position is increased by the sum of the width of that + glyph and N (an integer in basic units `u'). This command is a + `gtroff' extension; it is only used for devices whose `DESC' file + contains the `tcommand' keyword (*note DESC File Format::). + +`V N' + Move down to the absolute vertical position N (a non-negative + integer in basic units `u') relative to upper edge of current page. + +`v N' + Move N basic units `u' down (N is a non-negative integer). The + original UNIX troff manual allows negative values for N also, but + `gtroff' doesn't use this. + +`w' + Informs about a paddable white space to increase readability. The + spacing itself must be performed explicitly by a move command. -File: groff, Node: ms Footnotes, Prev: Example multi-page table, Up: ms Body Text +File: groff, Node: Simple Commands-Footnotes, Up: Simple Commands + + (1) `c' is actually a misnomer since it outputs a glyph. -Footnotes -......... + +File: groff, Node: Graphics Commands, Next: Device Control Commands, Prev: Simple Commands, Up: Command Reference + +8.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 Requests::. + + 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 analoguous 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 65536. + 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 65536 + (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 65536 + 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 point 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, Node: Device Control Commands, Next: Obsolete Command, Prev: Graphics Commands, Up: Command Reference - The `ms' macro package has a flexible footnote system. You can -specify either numbered footnotes or symbolic footnotes (that is, using -a marker such as a dagger symbol). +8.1.2.4 Device Control Commands +............................... - - String: \*[*] - Specifies the location of a numbered footnote marker in the text. +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). - - Macro: .FS - - Macro: .FE - Specifies the text of the footnote. The default action is to - create a numbered footnote; you can create a symbolic footnote by - specifying a "mark" glyph (such as `\[dg]' for the dagger glyph) - in the body text and as an argument to the `FS' macro, followed by - the text of the footnote and the `FE' macro. + 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'. - You can control how `groff' prints footnote numbers by changing the -value of the `FF' register. *Note ms Document Control Registers::. + 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 original UNIX troff manual writes + + pause device, can be restarted + +`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 GTROFF, this is actually + just ignored. + +`xT XXX<line break>' + The `T' stands for TYPESETTER. + + Set name of device to word XXX, a sequence of characters ended by + the next white space character. The possible device names coincide + with those from the `groff' `-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, Node: Obsolete Command, Prev: Device Control Commands, Up: Command Reference + +8.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 `gtroff', arbitrary syntactical space around and within this + command is allowed to be added. Only when a preceding command on + the same line ends with an argument of variable length a + separating space is 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, Node: ms Page Layout, Next: Differences from AT&T ms, Prev: ms Body Text, Up: ms +File: groff, Node: Intermediate Output Examples, Next: Output Language Compatibility, Prev: Command Reference, Up: gtroff Output + +8.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 very low resolution compared to + modern printers the intermediate output for the X Window 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, Node: Output Language Compatibility, Prev: Intermediate Output Examples, Up: gtroff Output + +8.1.4 Output Language Compatibility +----------------------------------- + +The intermediate output language of AT&T `troff' was first documented +in the UNIX troff manual, with later additions documented in `A +Typesetter-indenpendent TROFF', written by Brian Kernighan. + + The `gtroff' intermediate output format is compatible with this +specification except for the following features. -Page layout ------------ + * The classical quasi device independence is not yet implemented. - The default output from the `ms' macros provides a minimalist page -layout: it prints a single column, with the page number centered at the -top of each page. It prints no footers. + * 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. - You can change the layout by setting the proper number registers and -strings. + * 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, Node: Font Files, Prev: gtroff Output, Up: File formats + +8.2 Font Files +============== + +The `gtroff' font format is roughly a superset of the `ditroff' font +format (as used in later versions of AT&T `troff' and its descendants). +Unlike the `ditroff' font format, there is no associated binary +format; all files are text files.(1) (*note Font Files-Footnote-1::) +The font files for device NAME are stored in a directory `devNAME'. +There are two types of file: a device description file called `DESC' +and for each font F a font file called `F'. * Menu: -* ms Headers and Footers:: -* ms Margins:: -* ms Multiple Columns:: -* ms TOC:: -* ms Strings and Special Characters:: +* DESC File Format:: +* Font File Format:: -File: groff, Node: ms Headers and Footers, Next: ms Margins, Prev: ms Page Layout, Up: ms Page Layout +File: groff, Node: Font Files-Footnotes, Up: Font Files -Headers and footers -................... + (1) Plan 9 `troff' has also abandoned the binary format. - For documents that do not distinguish between odd and even pages, -set the following strings: + +File: groff, Node: DESC File Format, Next: Font File Format, Prev: Font Files, Up: Font Files + +8.2.1 `DESC' File Format +------------------------ + +The `DESC' file can contain the following types of line. Except for +the `charset' keyword which must comes last (if at all), the order of +the lines is not important. + +`res N' + There are N machine units per inch. + +`hor N' + The horizontal resolution is N machine units. All horizontal + quantities are rounded to be multiples of this value. + +`vert N' + The vertical resolution is N machine units. All vertical + quantities are rounded to be multiples of this value. + +`sizescale N' + The scale factor for point sizes. By default this has a value + of 1. One scaled point is equal to one point/N. The arguments to + the `unitwidth' and `sizes' commands are given in scaled points. + *Note Fractional Type Sizes::, for more information. + +`unitwidth N' + Quantities in the font files are given in machine units for fonts + whose point size is N scaled points. + +`prepro PROGRAM' + Call PROGRAM as a preprocessor. Currently, this keyword is used + by `groff' with option `-Thtml' only. + +`postpro PROGRAM' + Call PROGRAM as a postprocessor. For example, the line + + + postpro grodvi + + in the file `devdvi/DESC' makes `groff' call `grodvi' if option + `-Tdvi' is given (and `-Z' isn't used). + +`tcommand' + This means that the postprocessor can handle the `t' and `u' + intermediate output commands. + +`sizes S1 S2 ... SN 0' + This means that the device has fonts at S1, S2, ... SN scaled + points. The list of sizes must be terminated by 0 (this is digit + zero). Each SI can also be a range of sizes M-N. The list can + extend over more than one line. + +`styles S1 S2 ... SM' + The first M font positions are associated with styles S1 ... SM. + +`fonts N F1 F2 F3 ... FN' + Fonts F1 ... FN are mounted in the font positions M+1, ..., M+N + where M is the number of styles. This command may extend over + more than one line. A font name of 0 means no font is mounted on + the corresponding font position. + +`family FAM' + The default font family is FAM. + +`use_charnames_in_special' + This command indicates that `gtroff' should encode special + characters inside special commands. Currently, this is only used + by the HTML output device. *Note Postprocessor Access::. + +`papersize STRING ...' + Select a paper size. Valid values for STRING are the ISO paper + types `A0'-`A7', `B0'-`B7', `C0'-`C7', `D0'-`D7', `DL', and the US + paper types `letter', `legal', `tabloid', `ledger', `statement', + `executive', `com10', and `monarch'. Case is not significant for + STRING if it holds predefined paper types. Alternatively, STRING + can be a file name (e.g. `/etc/papersize'); if the file can be + opened, `groff' reads the first line and tests for the above paper + sizes. Finally, STRING can be a custom paper size in the format + `LENGTH,WIDTH' (no spaces before and after the comma). Both + LENGTH and WIDTH must have a unit appended; valid values are `i' + for inches, `C' for centimeters, `p' for points, and `P' for + picas. Example: `12c,235p'. An argument which starts with a + digit is always treated as a custom paper format. `papersize' + sets both the vertical and horizontal dimension of the output + medium. + + More than one argument can be specified; `groff' scans from left to + right and uses the first valid paper specification. + +`pass_filenames' + Tell `gtroff' to emit the name of the source file currently being + processed. This is achieved by the intermediate output command + `F'. Currently, this is only used by the HTML output device. + +`print PROGRAM' + Use PROGRAM as a spooler program for printing. If omitted, the + `-l' and `-L' options of `groff' are ignored. + +`charset' + This line and everything following in the file are ignored. It is + allowed for the sake of backwards compatibility. + + The `res', `unitwidth', `fonts', and `sizes' lines are mandatory. +Other commands are ignored by `gtroff' but may be used by +postprocessors to store arbitrary information about the device in the +`DESC' file. + + Here a list of obsolete keywords which are recognized by `groff' but +completely ignored: `spare1', `spare2', `biggestfont'. - - String: \*[LH] - - String: \*[CH] - - String: \*[RH] - Sets the left, center, and right headers. + +File: groff, Node: Font File Format, Prev: DESC File Format, Up: Font Files + +8.2.2 Font File Format +---------------------- + +A "font file", also (and probably better) called a "font description +file", has two sections. The first section is a sequence of lines each +containing a sequence of blank delimited words; the first word in the +line is a key, and subsequent words give a value for that key. + +`name F' + The name of the font is F. + +`spacewidth N' + The normal width of a space is N. + +`slant N' + The glyphs of the font have a slant of N degrees. (Positive means + forward.) + +`ligatures LIG1 LIG2 ... LIGN [0]' + Glyphs LIG1, LIG2, ..., LIGN are ligatures; possible ligatures are + `ff', `fi', `fl', `ffi' and `ffl'. For backwards compatibility, + the list of ligatures may be terminated with a 0. The list of + ligatures may not extend over more than one line. + +`special' + The font is "special"; this means that when a glyph is requested + that is not present in the current font, it is searched for in any + special fonts that are mounted. + + Other commands are ignored by `gtroff' but may be used by +postprocessors to store arbitrary information about the font in the font +file. + + The first section can contain comments which start with the `#' +character and extend to the end of a line. + + The second section contains one or two subsections. It must contain +a `charset' subsection and it may also contain a `kernpairs' +subsection. These subsections can appear in any order. Each +subsection starts with a word on a line by itself. + + The word `charset' starts the character set subsection.(1) (*note +Font File Format-Footnote-1::) The `charset' line is followed by a +sequence of lines. Each line gives information for one glyph. A line +comprises a number of fields separated by blanks or tabs. The format is + + NAME METRICS TYPE CODE [ENTITY-NAME] [`--' COMMENT] + +NAME identifies the glyph name(2) (*note Font File Format-Footnote-2::): +If NAME is a single character C then it corresponds to the `gtroff' +input character C; if it is of the form `\C' where C is a single +character, then it corresponds to the special character `\[C]'; +otherwise it corresponds to the special character `\[NAME]'. If it is +exactly two characters XX it can be entered as `\(XX'. Note that +single-letter special characters can't be accessed as `\C'; the only +exception is `\-' which is identical to `\[-]'. + + `gtroff' supports 8-bit input characters; however some utilities +have difficulties with eight-bit characters. For this reason, there is +a convention that the entity name `charN' is equivalent to the single +input character whose code is N. For example, `char163' would be +equivalent to the character with code 163 which is the pounds sterling +sign in the ISO Latin-1 character set. You shouldn't use `charN' +entities in font description files since they are related to input, not +output. Otherwise, you get hard-coded connections between input and +output encoding which prevents use of different (input) character sets. + + The name `---' is special and indicates that the glyph is unnamed; +such glyphs can only be used by means of the `\N' escape sequence in +`gtroff'. + + The TYPE field gives the glyph type: + +`1' + the glyph has a descender, for example, `p'; + +`2' + the glyph has an ascender, for example, `b'; + +`3' + the glyph has both an ascender and a descender, for example, `('. + + The CODE field gives the code which the postprocessor uses to print +the glyph. The glyph can also be input to `gtroff' using this code by +means of the `\N' escape sequence. CODE can be any integer. If it +starts with `0' it is interpreted as octal; if it starts with `0x' or +`0X' it is interpreted as hexadecimal. Note, however, that the `\N' +escape sequence only accepts a decimal integer. + + The ENTITY-NAME field gives an ASCII string identifying the glyph +which the postprocessor uses to print the `gtroff' glyph NAME. This +field is optional and has been introduced so that the HTML device +driver can encode its character set. For example, the glyph `\[Po]' is +represented as `£' in HTML 4.0. + + Anything on the line after the ENTITY-NAME field resp. after `--' +will be ignored. + + The METRICS field has the form: + + WIDTH[`,'HEIGHT[`,'DEPTH[`,'ITALIC-CORRECTION + [`,'LEFT-ITALIC-CORRECTION[`,'SUBSCRIPT-CORRECTION]]]]] + +There must not be any spaces between these subfields (it has been split +here into two lines for better legibility only). Missing subfields are +assumed to be 0. The subfields are all decimal integers. Since there +is no associated binary format, these values are not required to fit +into a variable of type `char' as they are in `ditroff'. The WIDTH +subfield gives the width of the glyph. The HEIGHT subfield gives the +height of the glyph (upwards 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 from the baseline to the lowest point below the +baseline to which the glyph extends (downwards is positive); if a glyph +does not extend below the baseline, it should be given a zero depth, +rather than a negative depth. The ITALIC-CORRECTION subfield gives the +amount of space that should be added after the glyph when it is +immediately to be followed by a glyph from a roman font. The +LEFT-ITALIC-CORRECTION subfield gives the amount of space that should +be added before the glyph when it is immediately to be preceded by a +glyph from a roman font. The SUBSCRIPT-CORRECTION gives the amount of +space that should be added after a glyph before adding a subscript. +This should be less than the italic correction. + + A line in the `charset' section can also have the format + + + NAME " + +This indicates that NAME is just another name for the glyph mentioned +in the preceding line. + + The word `kernpairs' starts the kernpairs section. This contains a +sequence of lines of the form: + + + C1 C2 N + +This means that when glyph C1 appears next to glyph C2 the space +between them should be increased by N. Most entries in the kernpairs +section have a negative value for N. - - String: \*[LF] - - String: \*[CF] - - String: \*[RF] - Sets the left, center, and right footers. + +File: groff, Node: Font File Format-Footnotes, Up: Font File Format + (1) This keyword is misnamed since it starts a list of ordered +glyphs, not characters. - For documents that need different information printed in the even -and odd pages, use the following macros: + (2) The distinction between input, characters, and output, glyphs, +is not clearly separated in the terminology of `groff'; for example, +the `char' request should be called `glyph' since it defines an output +entity. - - Macro: .OH 'left'center'right' - - Macro: .EH 'left'center'right' - - Macro: .OF 'left'center'right' - - Macro: .EF 'left'center'right' - The `OH' and `EH' macros define headers for the odd and even pages; - the `OF' and `EF' macros define footers for the odd and even pages. - This is more flexible than defining the individual strings. + +File: groff, Node: Installation, Next: Copying This Manual, Prev: File formats, Up: Top - You can replace the quote (`'') marks with any character not - appearing in the header or footer text. +9 Installation +************** -File: groff, Node: ms Margins, Next: ms Multiple Columns, Prev: ms Headers and Footers, Up: ms Page Layout +File: groff, Node: Copying This Manual, Next: Request Index, Prev: Installation, Up: Top -Margins -....... +Appendix A Copying This Manual +****************************** - You control margins using a set of number registers. *Note ms -Document Control Registers::, for details. +* Menu: + +* GNU Free Documentation License:: License for copying this manual. -File: groff, Node: ms Multiple Columns, Next: ms TOC, Prev: ms Margins, Up: ms Page Layout +File: groff, Node: GNU Free Documentation License, Up: Copying This Manual + +A.1 GNU Free Documentation License +================================== + + Version 1.2, November 2002 + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + + 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. + + 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 for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 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. + +A.1.1 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.2 + 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. -Multiple columns -................ + +File: groff, Node: Request Index, Next: Escape Index, Prev: Copying This Manual, Up: Top - The `ms' macros can set text in as many columns as will reasonably -fit on the page. The following macros are available; all of them force -a page break if a multi-column mode is already set. However, if the -current mode is single-column, starting a multi-column mode does *not* -force a page break. +Appendix B Request Index +************************ - - Macro: .1C - Single-column mode. +Requests appear without the leading control character (normally either +`.' or `''). - - Macro: .2C - Two-column mode. + +* Menu: - - Macro: .MC [width [gutter]] - Multi-column mode. If you specify no arguments, it is equivalent - to the `2C' macro. Otherwise, WIDTH is the width of each column - and GUTTER is the space between columns. The `MINGW' number - register controls the default gutter width. +* ab: Debugging. (line 40) +* ad: Manipulating Filling and Adjusting. + (line 52) +* af: Assigning Formats. (line 13) +* aln: Setting Registers. (line 79) +* als: Strings. (line 224) +* am: Writing Macros. (line 107) +* am1: Writing Macros. (line 108) +* ami: Writing Macros. (line 109) +* ami1: Writing Macros. (line 110) +* as: Strings. (line 170) +* as1: Strings. (line 171) +* asciify: Diversions. (line 195) +* backtrace: Debugging. (line 94) +* bd: Artificial Fonts. (line 96) +* blm: Blank Line Traps. (line 7) +* box: Diversions. (line 25) +* boxa: Diversions. (line 26) +* bp: Page Control. (line 7) +* br: Manipulating Filling and Adjusting. + (line 12) +* break: while. (line 73) +* brp: Manipulating Filling and Adjusting. + (line 112) +* c2: Character Translations. + (line 16) +* cc: Character Translations. + (line 10) +* ce: Manipulating Filling and Adjusting. + (line 189) +* cf: I/O. (line 49) +* cflags: Using Symbols. (line 241) +* ch: Page Location Traps. (line 106) +* char: Using Symbols. (line 281) +* chop: Strings. (line 231) +* close: I/O. (line 230) +* color: Colors. (line 7) +* composite: Using Symbols. (line 197) +* continue: while. (line 77) +* cp: Implementation Differences. + (line 23) +* cs: Artificial Fonts. (line 127) +* cu: Artificial Fonts. (line 87) +* da: Diversions. (line 18) +* de: Writing Macros. (line 10) +* de1: Writing Macros. (line 11) +* defcolor: Colors. (line 21) +* dei: Writing Macros. (line 12) +* dei1: Writing Macros. (line 13) +* di: Diversions. (line 17) +* do: Implementation Differences. + (line 24) +* ds: Strings. (line 11) +* ds1: Strings. (line 12) +* dt: Diversion Traps. (line 7) +* ec: Character Translations. + (line 47) +* ecr: Character Translations. + (line 59) +* ecs: Character Translations. + (line 58) +* el: if-else. (line 28) +* em: End-of-input Traps. (line 7) +* eo: Character Translations. + (line 22) +* ev: Environments. (line 38) +* evc: Environments. (line 72) +* ex: Debugging. (line 45) +* fam: Font Families. (line 19) +* fc: Fields. (line 18) +* fchar: Using Symbols. (line 282) +* fcolor: Colors. (line 85) +* fi: Manipulating Filling and Adjusting. + (line 30) +* fl: Debugging. (line 85) +* fp: Font Positions. (line 11) +* fschar: Using Symbols. (line 283) +* fspecial: Special Fonts. (line 18) +* ft <1>: Font Positions. (line 58) +* ft: Changing Fonts. (line 7) +* ftr: Changing Fonts. (line 53) +* gcolor: Colors. (line 51) +* hc: Manipulating Hyphenation. + (line 105) +* hcode: Manipulating Hyphenation. + (line 174) +* hla: Manipulating Hyphenation. + (line 253) +* hlm: Manipulating Hyphenation. + (line 45) +* hpf: Manipulating Hyphenation. + (line 114) +* hpfa: Manipulating Hyphenation. + (line 115) +* hpfcode: Manipulating Hyphenation. + (line 116) +* hw: Manipulating Hyphenation. + (line 61) +* hy: Manipulating Hyphenation. + (line 9) +* hym: Manipulating Hyphenation. + (line 209) +* hys: Manipulating Hyphenation. + (line 224) +* ie: if-else. (line 27) +* if: if-else. (line 10) +* ig: Comments. (line 67) +* in: Line Layout. (line 91) +* it: Input Line Traps. (line 7) +* itc: Input Line Traps. (line 8) +* kern: Ligatures and Kerning. + (line 41) +* lc: Leaders. (line 23) +* length: Strings. (line 204) +* lf: Debugging. (line 10) +* lg: Ligatures and Kerning. + (line 23) +* linetabs: Tabs and Fields. (line 147) +* ll: Line Layout. (line 145) +* ls: Manipulating Spacing. + (line 51) +* lt: Page Layout. (line 60) +* mc: Miscellaneous. (line 76) +* mk: Page Motions. (line 10) +* mso: I/O. (line 41) +* na: Manipulating Filling and Adjusting. + (line 104) +* ne: Page Control. (line 34) +* nf: Manipulating Filling and Adjusting. + (line 41) +* nh: Manipulating Hyphenation. + (line 37) +* nm: Miscellaneous. (line 10) +* nn: Miscellaneous. (line 72) +* nop: if-else. (line 24) +* nr <1>: Auto-increment. (line 11) +* nr: Setting Registers. (line 9) +* nroff: Troff and Nroff Mode. + (line 32) +* ns: Manipulating Spacing. + (line 113) +* nx: I/O. (line 74) +* open: I/O. (line 198) +* opena: I/O. (line 199) +* os: Page Control. (line 55) +* output: Diversions. (line 180) +* pc: Page Layout. (line 89) +* pi: I/O. (line 138) +* pl: Page Layout. (line 10) +* pm: Debugging. (line 64) +* pn: Page Layout. (line 77) +* pnr: Debugging. (line 75) +* po: Line Layout. (line 61) +* ps: Changing Type Sizes. (line 7) +* psbb: Miscellaneous. (line 141) +* pso: I/O. (line 30) +* ptr: Debugging. (line 79) +* pvs: Changing Type Sizes. (line 133) +* rchar: Using Symbols. (line 340) +* rd: I/O. (line 79) +* return: Writing Macros. (line 143) +* rfschar: Using Symbols. (line 341) +* rj: Manipulating Filling and Adjusting. + (line 238) +* rm: Strings. (line 219) +* rn: Strings. (line 216) +* rnn: Setting Registers. (line 75) +* rr: Setting Registers. (line 71) +* rs: Manipulating Spacing. + (line 114) +* rt: Page Motions. (line 11) +* schar: Using Symbols. (line 284) +* shc: Manipulating Hyphenation. + (line 240) +* shift: Parameters. (line 30) +* sizes: Changing Type Sizes. (line 69) +* so: I/O. (line 9) +* sp: Manipulating Spacing. + (line 7) +* special: Special Fonts. (line 17) +* spreadwarn: Debugging. (line 131) +* ss: Manipulating Filling and Adjusting. + (line 134) +* sty: Font Families. (line 61) +* substring: Strings. (line 188) +* sv: Page Control. (line 54) +* sy: I/O. (line 160) +* ta: Tabs and Fields. (line 14) +* tc: Tabs and Fields. (line 139) +* ti: Line Layout. (line 117) +* tkf: Ligatures and Kerning. + (line 60) +* tl: Page Layout. (line 35) +* tm: Debugging. (line 25) +* tm1: Debugging. (line 26) +* tmc: Debugging. (line 27) +* tr: Character Translations. + (line 153) +* trf: I/O. (line 48) +* trin: Character Translations. + (line 154) +* trnt: Character Translations. + (line 245) +* troff: Troff and Nroff Mode. + (line 24) +* uf: Artificial Fonts. (line 91) +* ul: Artificial Fonts. (line 65) +* unformat: Diversions. (line 215) +* vpt: Page Location Traps. (line 17) +* vs: Changing Type Sizes. (line 84) +* warn: Debugging. (line 154) +* warnscale: Debugging. (line 127) +* wh: Page Location Traps. (line 29) +* while: while. (line 10) +* write: I/O. (line 210) +* writec: I/O. (line 211) +* writem: I/O. (line 221) -File: groff, Node: ms TOC, Next: ms Strings and Special Characters, Prev: ms Multiple Columns, Up: ms Page Layout +File: groff, Node: Escape Index, Next: Operator Index, Prev: Request Index, Up: Top -Creating a table of contents -............................ +Appendix C Escape Index +*********************** - The facilities in the `ms' macro package for creating a table of -contents are semi-automated at best. Assuming that you want the table -of contents to consist of the document's headings, you need to repeat -those headings wrapped in `XS' and `XE' macros. +Any escape sequence `\X' with X not in the list below emits a warning, +printing glyph X. - - Macro: .XS [page] - - Macro: .XA [page] - - Macro: .XE - These macros define a table of contents or an individual entry in - the table of contents, depending on their use. The macros are - very simple; they cannot indent a heading based on its level. The - easiest way to work around this is to add tabs to the table of - contents string. The following is an example: + +* Menu: +* \: Using Symbols. (line 139) +* \!: Diversions. (line 133) +* \": Comments. (line 10) +* \#: Comments. (line 50) +* \$: Parameters. (line 19) +* \$*: Parameters. (line 38) +* \$0: Parameters. (line 48) +* \$@: Parameters. (line 39) +* \%: Manipulating Hyphenation. + (line 84) +* \&: Ligatures and Kerning. + (line 102) +* \': Using Symbols. (line 229) +* \): Ligatures and Kerning. + (line 131) +* \*: Strings. (line 13) +* \,: Ligatures and Kerning. + (line 92) +* \-: Using Symbols. (line 238) +* \.: Character Translations. + (line 126) +* \/: Ligatures and Kerning. + (line 80) +* \0: Page Motions. (line 139) +* \<colon>: Manipulating Hyphenation. + (line 85) +* \<RET>: Line Control. (line 43) +* \<SP>: Page Motions. (line 123) +* \?: Diversions. (line 134) +* \\: Character Translations. + (line 68) +* \^: Page Motions. (line 135) +* \`: Using Symbols. (line 234) +* \a: Leaders. (line 18) +* \A: Identifiers. (line 55) +* \b: Drawing Requests. (line 223) +* \B: Expressions. (line 65) +* \C: Using Symbols. (line 191) +* \c: Line Control. (line 44) +* \D: Drawing Requests. (line 71) +* \d: Page Motions. (line 109) +* \E: Character Translations. + (line 70) +* \e: Character Translations. + (line 69) +* \f: Font Positions. (line 59) +* \F: Font Families. (line 21) +* \f: Changing Fonts. (line 8) +* \g: Assigning Formats. (line 75) +* \h: Page Motions. (line 112) +* \H: Artificial Fonts. (line 13) +* \k: Page Motions. (line 203) +* \L: Drawing Requests. (line 50) +* \l: Drawing Requests. (line 16) +* \M: Colors. (line 86) +* \m: Colors. (line 52) +* \N: Using Symbols. (line 207) +* \n <1>: Auto-increment. (line 19) +* \n: Interpolating Registers. + (line 9) +* \O: Suppressing output. (line 7) +* \o: Page Motions. (line 218) +* \p: Manipulating Filling and Adjusting. + (line 113) +* \r: Page Motions. (line 103) +* \R: Setting Registers. (line 10) +* \s: Changing Type Sizes. (line 10) +* \S: Artificial Fonts. (line 45) +* \t: Tabs and Fields. (line 10) +* \u: Page Motions. (line 106) +* \V: I/O. (line 248) +* \v: Page Motions. (line 87) +* \w: Page Motions. (line 147) +* \X: Postprocessor Access. + (line 11) +* \x: Manipulating Spacing. + (line 71) +* \Y: Postprocessor Access. + (line 25) +* \Z: Page Motions. (line 226) +* \z: Page Motions. (line 222) +* \{: if-else. (line 38) +* \|: Page Motions. (line 131) +* \}: if-else. (line 38) +* \~: Page Motions. (line 127) - .NH 1 - Introduction - .XS - Introduction - .XE - .LP - ... - .CW - .NH 2 - Methodology - .XS - Methodology - .XE - .LP - ... + +File: groff, Node: Operator Index, Next: Register Index, Prev: Escape Index, Up: Top - You can manually create a table of contents by beginning with the - `XS' macro for the first entry, specifying the page number for - that entry as the argument to `XS'. Add subsequent entries using - the `XA' macro, specifying the page number for that entry as the - argument to `XA'. The following is an example: +Appendix D Operator Index +************************* + +* Menu: - .XS 1 - Introduction - .XA 2 - A Brief History of the Universe - .XA 729 - Details of Galactic Formation - ... - .XE +* !: Expressions. (line 21) +* %: Expressions. (line 8) +* &: Expressions. (line 19) +* (: Expressions. (line 41) +* ): Expressions. (line 41) +* *: Expressions. (line 8) +* +: Expressions. (line 8) +* -: Expressions. (line 8) +* /: Expressions. (line 8) +* <: Expressions. (line 15) +* <=: Expressions. (line 15) +* <?: Expressions. (line 26) +* <colon>: Expressions. (line 19) +* =: Expressions. (line 15) +* ==: Expressions. (line 15) +* >: Expressions. (line 15) +* >=: Expressions. (line 15) +* >?: Expressions. (line 26) + + +File: groff, Node: Register Index, Next: Macro Index, Prev: Operator Index, Up: Top + +Appendix E Register Index +************************* + +The macro package or program a specific register belongs to is appended +in brackets. + + A register name `x' consisting of exactly one character can be +accessed as `\nx'. A register name `xx' consisting of exactly two +characters can be accessed as `\n(xx'. Register names `xxx' of any +length can be accessed as `\n[xxx]'. + + +* Menu: + +* $$: Built-in Registers. (line 96) +* % <1>: Page Control. (line 10) +* %: Page Layout. (line 89) +* .$: Parameters. (line 10) +* .a: Manipulating Spacing. + (line 72) +* .A: Built-in Registers. (line 103) +* .b: Artificial Fonts. (line 98) +* .C: Implementation Differences. + (line 25) +* .c: Built-in Registers. (line 73) +* .cdp: Environments. (line 96) +* .ce: Manipulating Filling and Adjusting. + (line 190) +* .cht: Environments. (line 95) +* .color: Colors. (line 8) +* .csk: Environments. (line 97) +* .d: Diversions. (line 62) +* .ev: Environments. (line 39) +* .f: Font Positions. (line 12) +* .F: Built-in Registers. (line 12) +* .fam: Font Families. (line 20) +* .fn: Font Families. (line 24) +* .fp: Font Positions. (line 13) +* .g: Built-in Registers. (line 99) +* .h: Diversions. (line 69) +* .H: Built-in Registers. (line 15) +* .height: Artificial Fonts. (line 16) +* .hla: Manipulating Hyphenation. + (line 254) +* .hlc: Manipulating Hyphenation. + (line 47) +* .hlm: Manipulating Hyphenation. + (line 46) +* .hy: Manipulating Hyphenation. + (line 10) +* .hym: Manipulating Hyphenation. + (line 210) +* .hys: Manipulating Hyphenation. + (line 225) +* .i: Line Layout. (line 94) +* .in: Line Layout. (line 120) +* .int: Line Control. (line 45) +* .j: Manipulating Filling and Adjusting. + (line 53) +* .k: Page Motions. (line 214) +* .kern: Ligatures and Kerning. + (line 42) +* .l: Line Layout. (line 148) +* .L: Manipulating Spacing. + (line 52) +* .lg: Ligatures and Kerning. + (line 24) +* .linetabs: Tabs and Fields. (line 148) +* .ll: Line Layout. (line 149) +* .lt: Page Layout. (line 63) +* .M: Colors. (line 89) +* .m: Colors. (line 55) +* .n: Environments. (line 112) +* .ne: Page Location Traps. (line 118) +* .ns: Manipulating Spacing. + (line 115) +* .o: Line Layout. (line 64) +* .p: Page Layout. (line 13) +* .P: Built-in Registers. (line 108) +* .pe: Page Location Traps. (line 139) +* .pn: Page Layout. (line 80) +* .ps: Fractional Type Sizes. + (line 35) +* .psr: Fractional Type Sizes. + (line 42) +* .pvs: Changing Type Sizes. (line 136) +* .rj: Manipulating Filling and Adjusting. + (line 239) +* .s: Changing Type Sizes. (line 11) +* .slant: Artificial Fonts. (line 46) +* .sr: Fractional Type Sizes. + (line 43) +* .ss: Manipulating Filling and Adjusting. + (line 135) +* .sss: Manipulating Filling and Adjusting. + (line 136) +* .sty: Changing Fonts. (line 11) +* .t: Page Location Traps. (line 97) +* .T: Built-in Registers. (line 114) +* .tabs: Tabs and Fields. (line 15) +* .trunc: Page Location Traps. (line 127) +* .u: Manipulating Filling and Adjusting. + (line 31) +* .v: Changing Type Sizes. (line 87) +* .V: Built-in Registers. (line 23) +* .vpt: Page Location Traps. (line 18) +* .w: Environments. (line 94) +* .warn: Debugging. (line 155) +* .x: Built-in Registers. (line 85) +* .Y: Built-in Registers. (line 93) +* .y: Built-in Registers. (line 89) +* .z: Diversions. (line 61) +* c.: Built-in Registers. (line 74) +* ct: Page Motions. (line 152) +* dl: Diversions. (line 87) +* dn: Diversions. (line 86) +* dw: Built-in Registers. (line 39) +* dy: Built-in Registers. (line 42) +* FAM [ms]: ms Document Control Registers. + (line 110) +* FF [ms]: ms Document Control Registers. + (line 184) +* FI [ms]: ms Document Control Registers. + (line 177) +* FL [ms]: ms Document Control Registers. + (line 170) +* FM [ms]: ms Document Control Registers. + (line 47) +* FPD [ms]: ms Document Control Registers. + (line 221) +* FPS [ms]: ms Document Control Registers. + (line 204) +* FVS [ms]: ms Document Control Registers. + (line 212) +* GROWPS [ms]: ms Document Control Registers. + (line 88) +* GS [ms]: Differences from AT&T ms. + (line 46) +* HM [ms]: ms Document Control Registers. + (line 40) +* HORPHANS [ms]: ms Document Control Registers. + (line 154) +* hours: Built-in Registers. (line 35) +* hp: Page Motions. (line 211) +* HY [ms]: ms Document Control Registers. + (line 101) +* LL [ms]: ms Document Control Registers. + (line 25) +* llx: Miscellaneous. (line 142) +* lly: Miscellaneous. (line 143) +* ln: Built-in Registers. (line 79) +* LT [ms]: ms Document Control Registers. + (line 32) +* MINGW [ms] <1>: Additional ms Macros. + (line 28) +* MINGW [ms]: ms Document Control Registers. + (line 231) +* minutes: Built-in Registers. (line 31) +* mo: Built-in Registers. (line 45) +* nl: Page Control. (line 68) +* opmaxx: Suppressing output. (line 19) +* opmaxy: Suppressing output. (line 19) +* opminx: Suppressing output. (line 19) +* opminy: Suppressing output. (line 19) +* PD [ms]: ms Document Control Registers. + (line 127) +* PI [ms]: ms Document Control Registers. + (line 120) +* PO [ms]: ms Document Control Registers. + (line 16) +* PORPHANS [ms]: ms Document Control Registers. + (line 142) +* PS [ms]: ms Document Control Registers. + (line 57) +* ps4html [grohtml]: grohtml specific registers and strings. + (line 7) +* PSINCR [ms]: ms Document Control Registers. + (line 77) +* QI [ms]: ms Document Control Registers. + (line 134) +* rsb: Page Motions. (line 151) +* rst: Page Motions. (line 150) +* sb: Page Motions. (line 149) +* seconds: Built-in Registers. (line 26) +* skw: Page Motions. (line 154) +* slimit: Debugging. (line 119) +* ssc: Page Motions. (line 153) +* st: Page Motions. (line 148) +* systat: I/O. (line 161) +* urx: Miscellaneous. (line 144) +* ury: Miscellaneous. (line 145) +* VS [ms]: ms Document Control Registers. + (line 67) +* year: Built-in Registers. (line 48) +* yr: Built-in Registers. (line 51) + + +File: groff, Node: Macro Index, Next: String Index, Prev: Register Index, Up: Top + +Appendix F Macro Index +********************** + +The macro package a specific macro belongs to is appended in brackets. +They appear without the leading control character (normally `.'). + +* Menu: + +* 1C [ms]: ms Multiple Columns. (line 13) +* 2C [ms]: ms Multiple Columns. (line 16) +* [ [ms]: ms Insertions. (line 33) +* ] [ms]: ms Insertions. (line 34) +* AB [ms]: ms Cover Page Macros. + (line 60) +* AE [ms]: ms Cover Page Macros. + (line 65) +* AI [ms]: ms Cover Page Macros. + (line 56) +* AM [ms] <1>: Additional ms Macros. + (line 10) +* AM [ms]: ms Strings and Special Characters. + (line 51) +* AT [man]: Miscellaneous man macros. + (line 26) +* AU [ms]: ms Cover Page Macros. + (line 38) +* B [man]: Man font macros. (line 48) +* B [ms]: Highlighting in ms. (line 10) +* B1 [ms]: ms Displays and Keeps. + (line 94) +* B2 [ms]: ms Displays and Keeps. + (line 95) +* BD [ms]: ms Displays and Keeps. + (line 31) +* BI [man]: Man font macros. (line 18) +* BI [ms]: Highlighting in ms. (line 39) +* BR [man]: Man font macros. (line 40) +* BT [man]: Optional man extensions. + (line 21) +* BX [ms]: Highlighting in ms. (line 43) +* CD [ms]: ms Displays and Keeps. + (line 41) +* CT [man]: Optional man extensions. + (line 36) +* CW [man]: Optional man extensions. + (line 39) +* CW [ms] <1>: Additional ms Macros. + (line 19) +* CW [ms]: Highlighting in ms. (line 35) +* DA [ms]: ms Cover Page Macros. + (line 23) +* De [man]: Optional man extensions. + (line 45) +* De [ms]: ms Displays and Keeps. + (line 57) +* DE [ms]: ms Displays and Keeps. + (line 16) +* Ds [man]: Optional man extensions. + (line 42) +* DS [ms]: Additional ms Macros. + (line 14) +* Ds [ms]: ms Displays and Keeps. + (line 56) +* DS [ms]: ms Displays and Keeps. + (line 14) +* DT [man]: Miscellaneous man macros. + (line 10) +* EE [man]: Optional man extensions. + (line 52) +* EF [ms]: ms Headers and Footers. + (line 26) +* EH [ms]: ms Headers and Footers. + (line 24) +* EN [ms]: ms Insertions. (line 28) +* EQ [ms]: ms Insertions. (line 27) +* EX [man]: Optional man extensions. + (line 48) +* FE [ms]: ms Footnotes. (line 15) +* FS [ms]: ms Footnotes. (line 14) +* G [man]: Optional man extensions. + (line 55) +* GL [man]: Optional man extensions. + (line 60) +* HB [man]: Optional man extensions. + (line 65) +* HP [man]: Man usage. (line 98) +* I [man]: Man font macros. (line 53) +* I [ms]: Highlighting in ms. (line 31) +* IB [man]: Man font macros. (line 28) +* ID [ms]: ms Displays and Keeps. + (line 23) +* IP [man]: Man usage. (line 78) +* IP [ms]: Lists in ms. (line 9) +* IR [man]: Man font macros. (line 36) +* IX [ms]: Additional ms Macros. + (line 22) +* KE [ms]: ms Displays and Keeps. + (line 73) +* KF [ms]: ms Displays and Keeps. + (line 77) +* KS [ms]: ms Displays and Keeps. + (line 72) +* LD [ms]: ms Displays and Keeps. + (line 15) +* LG [ms]: Highlighting in ms. (line 52) +* LP [man]: Man usage. (line 68) +* LP [ms]: Paragraphs in ms. (line 10) +* MC [ms]: ms Multiple Columns. (line 19) +* MS [man]: Optional man extensions. + (line 73) +* ND [ms]: ms Cover Page Macros. + (line 28) +* NE [man]: Optional man extensions. + (line 85) +* NH [ms]: Headings in ms. (line 13) +* NL [ms]: Highlighting in ms. (line 64) +* NT [man]: Optional man extensions. + (line 78) +* OF [ms]: ms Headers and Footers. + (line 25) +* OH [ms]: ms Headers and Footers. + (line 23) +* P [man]: Man usage. (line 70) +* P1 [ms]: ms Cover Page Macros. + (line 19) +* PD [man]: Miscellaneous man macros. + (line 15) +* PE [ms]: ms Insertions. (line 21) +* Pn [man]: Optional man extensions. + (line 92) +* PN [man]: Optional man extensions. + (line 88) +* PP [man]: Man usage. (line 69) +* PP [ms]: Paragraphs in ms. (line 9) +* PS [ms]: ms Insertions. (line 20) +* PT [man]: Optional man extensions. + (line 16) +* PX [ms]: ms TOC. (line 65) +* QP [ms]: Paragraphs in ms. (line 13) +* R [man]: Optional man extensions. + (line 98) +* R [ms]: Highlighting in ms. (line 27) +* RB [man]: Man font macros. (line 44) +* RD [ms]: ms Displays and Keeps. + (line 49) +* RE [man]: Man usage. (line 115) +* RE [ms]: Indentation values in ms. + (line 12) +* RI [man]: Man font macros. (line 32) +* RN [man]: Optional man extensions. + (line 101) +* RP [ms]: ms Cover Page Macros. + (line 10) +* RS [man]: Man usage. (line 106) +* RS [ms]: Indentation values in ms. + (line 11) +* SB [man]: Man font macros. (line 14) +* SH [man]: Man usage. (line 32) +* SH [ms]: Headings in ms. (line 43) +* SM [man]: Man font macros. (line 10) +* SM [ms]: Highlighting in ms. (line 58) +* SS [man]: Man usage. (line 41) +* TA [ms]: Tabstops in ms. (line 10) +* TB [man]: Optional man extensions. + (line 70) +* TC [ms]: ms TOC. (line 55) +* TE [ms]: ms Insertions. (line 12) +* TH [man]: Man usage. (line 11) +* TL [ms]: ms Cover Page Macros. + (line 33) +* TP [man]: Man usage. (line 49) +* TS [ms]: ms Insertions. (line 11) +* UC [man]: Miscellaneous man macros. + (line 43) +* UL [ms]: Highlighting in ms. (line 47) +* VE [man]: Optional man extensions. + (line 108) +* VS [man]: Optional man extensions. + (line 104) +* XA [ms]: ms TOC. (line 13) +* XE [ms]: ms TOC. (line 14) +* XP [ms]: Paragraphs in ms. (line 18) +* XS [ms]: ms TOC. (line 12) + + +File: groff, Node: String Index, Next: Glyph Name Index, Prev: Macro Index, Up: Top + +Appendix G String Index +*********************** + +The macro package or program a specific string belongs to is appended in +brackets. + + A string name `x' consisting of exactly one character can be +accessed as `\*x'. A string name `xx' consisting of exactly two +characters can be accessed as `\*(xx'. String names `xxx' of any +length can be accessed as `\*[xxx]'. + + +* Menu: + +* ! [ms]: ms Strings and Special Characters. + (line 101) +* ' [ms]: ms Strings and Special Characters. + (line 65) +* * [ms]: ms Footnotes. (line 11) +* , [ms]: ms Strings and Special Characters. + (line 74) +* - [ms]: ms Strings and Special Characters. + (line 41) +* . [ms]: ms Strings and Special Characters. + (line 89) +* .T: Built-in Registers. (line 119) +* 3 [ms]: ms Strings and Special Characters. + (line 107) +* 8 [ms]: ms Strings and Special Characters. + (line 104) +* ? [ms]: ms Strings and Special Characters. + (line 98) +* \*[<colon>] [ms]: ms Strings and Special Characters. + (line 80) +* ^ [ms]: ms Strings and Special Characters. + (line 71) +* _ [ms]: ms Strings and Special Characters. + (line 86) +* ` [ms]: ms Strings and Special Characters. + (line 68) +* ABSTRACT [ms]: ms Strings and Special Characters. + (line 15) +* Ae [ms]: ms Strings and Special Characters. + (line 128) +* ae [ms]: ms Strings and Special Characters. + (line 125) +* CF [ms]: ms Headers and Footers. + (line 16) +* CH [ms]: ms Headers and Footers. + (line 11) +* d- [ms]: ms Strings and Special Characters. + (line 119) +* D- [ms]: ms Strings and Special Characters. + (line 116) +* HF [man]: Predefined man strings. + (line 12) +* LF [ms]: ms Headers and Footers. + (line 15) +* LH [ms]: ms Headers and Footers. + (line 10) +* lq [man]: Predefined man strings. + (line 21) +* MONTH1 [ms]: ms Strings and Special Characters. + (line 23) +* MONTH10 [ms]: ms Strings and Special Characters. + (line 32) +* MONTH11 [ms]: ms Strings and Special Characters. + (line 33) +* MONTH12 [ms]: ms Strings and Special Characters. + (line 34) +* MONTH2 [ms]: ms Strings and Special Characters. + (line 24) +* MONTH3 [ms]: ms Strings and Special Characters. + (line 25) +* MONTH4 [ms]: ms Strings and Special Characters. + (line 26) +* MONTH5 [ms]: ms Strings and Special Characters. + (line 27) +* MONTH6 [ms]: ms Strings and Special Characters. + (line 28) +* MONTH7 [ms]: ms Strings and Special Characters. + (line 29) +* MONTH8 [ms]: ms Strings and Special Characters. + (line 30) +* MONTH9 [ms]: ms Strings and Special Characters. + (line 31) +* o [ms]: ms Strings and Special Characters. + (line 92) +* q [ms]: ms Strings and Special Characters. + (line 122) +* Q [ms]: ms Strings and Special Characters. + (line 44) +* R [man]: Predefined man strings. + (line 15) +* REFERENCES [ms]: ms Strings and Special Characters. + (line 11) +* RF [ms]: ms Headers and Footers. + (line 17) +* RH [ms]: ms Headers and Footers. + (line 12) +* rq [man]: Predefined man strings. + (line 22) +* S [man]: Predefined man strings. + (line 9) +* SN [ms]: Headings in ms. (line 22) +* SN-DOT [ms]: Headings in ms. (line 23) +* SN-NO-DOT [ms]: Headings in ms. (line 24) +* th [ms]: ms Strings and Special Characters. + (line 113) +* Th [ms]: ms Strings and Special Characters. + (line 110) +* Tm [man]: Predefined man strings. + (line 18) +* TOC [ms]: ms Strings and Special Characters. + (line 19) +* U [ms]: ms Strings and Special Characters. + (line 45) +* v [ms]: ms Strings and Special Characters. + (line 83) +* www-image-template [grohtml]: grohtml specific registers and strings. + (line 8) +* { [ms]: Highlighting in ms. (line 68) +* } [ms]: Highlighting in ms. (line 69) +* ~ [ms]: ms Strings and Special Characters. + (line 77) + + +File: groff, Node: Glyph Name Index, Next: Font File Keyword Index, Prev: String Index, Up: Top + +Appendix H Glyph Name Index +*************************** + +A glyph name `xx' consisting of exactly two characters can be accessed +as `\(xx'. Glyph names `xxx' of any length can be accessed as `\[xxx]'. - - Macro: .TC [`no'] - Prints the table of contents on a new page, setting the page - number to *i* (Roman numeral one). You should usually place this - macro at the end of the file, since `groff' is a single-pass - formatter and can only print what has been collected up to the - point that the `TC' macro appears. + +File: groff, Node: Font File Keyword Index, Next: Program and File Index, Prev: Glyph Name Index, Up: Top - The optional argument `no' suppresses printing the title specified - by the string register `TOC'. +Appendix I Font File Keyword Index +********************************** - - Macro: .PX [`no'] - Prints the table of contents on a new page, using the current page - numbering sequence. Use this macro to print a manually-generated - table of contents at the beginning of your document. + +* Menu: - The optional argument `no' suppresses printing the title specified - by the string register `TOC'. +* #: Font File Format. (line 36) +* ---: Font File Format. (line 51) +* biggestfont: DESC File Format. (line 109) +* charset <1>: Font File Format. (line 44) +* charset: DESC File Format. (line 101) +* family <1>: DESC File Format. (line 64) +* family <2>: Font Positions. (line 61) +* family: Changing Fonts. (line 11) +* fonts <1>: DESC File Format. (line 58) +* fonts <2>: Special Fonts. (line 18) +* fonts: Using Symbols. (line 15) +* hor: DESC File Format. (line 14) +* kernpairs: Font File Format. (line 135) +* ligatures: Font File Format. (line 22) +* name: Font File Format. (line 12) +* papersize: DESC File Format. (line 72) +* pass_filenames: DESC File Format. (line 92) +* postpro: DESC File Format. (line 36) +* prepro: DESC File Format. (line 32) +* print: DESC File Format. (line 97) +* res: DESC File Format. (line 11) +* sizes: DESC File Format. (line 49) +* sizescale: DESC File Format. (line 22) +* slant: Font File Format. (line 18) +* spacewidth: Font File Format. (line 15) +* spare1: DESC File Format. (line 109) +* spare2: DESC File Format. (line 109) +* special <1>: Font File Format. (line 28) +* special: Artificial Fonts. (line 116) +* styles <1>: DESC File Format. (line 55) +* styles <2>: Font Positions. (line 61) +* styles <3>: Font Families. (line 76) +* styles: Changing Fonts. (line 11) +* tcommand: DESC File Format. (line 45) +* unitwidth: DESC File Format. (line 28) +* use_charnames_in_special <1>: DESC File Format. (line 67) +* use_charnames_in_special: Postprocessor Access. + (line 17) +* vert: DESC File Format. (line 18) - The `Groff and Friends HOWTO' includes a `sed' script that -automatically inserts `XS' and `XE' macro entries after each heading in -a document. + +File: groff, Node: Program and File Index, Next: Concept Index, Prev: Font File Keyword Index, Up: Top - Altering the `NH' macro to automatically build the table of contents -is perhaps initially more difficult, but would save a great deal of -time in the long run if you use `ms' regularly. +Appendix J Program and File Index +********************************* + +* Menu: + +* an.tmac: man. (line 6) +* changebar: Miscellaneous. (line 111) +* composite.tmac: Using Symbols. (line 197) +* cp1047.tmac: Input Encodings. (line 9) +* DESC <1>: Special Fonts. (line 18) +* DESC <2>: Using Symbols. (line 15) +* DESC <3>: Font Positions. (line 61) +* DESC <4>: Font Families. (line 76) +* DESC: Changing Fonts. (line 11) +* DESC file format: DESC File Format. (line 6) +* DESC, and font mounting: Font Positions. (line 37) +* DESC, and use_charnames_in_special: Postprocessor Access. + (line 17) +* ditroff: History. (line 58) +* ec.tmac: Input Encodings. (line 41) +* eqn: ms Insertions. (line 7) +* freeeuro.pfa: Input Encodings. (line 41) +* geqn: Groff Options. (line 6) +* geqn, invocation in manual pages: Preprocessors in man pages. + (line 12) +* ggrn: Groff Options. (line 6) +* gpic: Groff Options. (line 6) +* grap: Groff Options. (line 6) +* grefer: Groff Options. (line 6) +* grefer, invocation in manual pages: Preprocessors in man pages. + (line 12) +* groff: Groff Options. (line 6) +* grog: grog. (line 6) +* grohtml: Miscellaneous man macros. + (line 6) +* gsoelim: Groff Options. (line 6) +* gtbl: Groff Options. (line 6) +* gtbl, invocation in manual pages: Preprocessors in man pages. + (line 12) +* gtroff: Groff Options. (line 6) +* hyphen.us: Manipulating Hyphenation. + (line 161) +* hyphenex.us: Manipulating Hyphenation. + (line 161) +* latin1.tmac: Input Encodings. (line 14) +* latin2.tmac: Input Encodings. (line 18) +* latin9.tmac: Input Encodings. (line 23) +* makeindex: Indices. (line 10) +* man, invocation of preprocessors: Preprocessors in man pages. + (line 12) +* man-old.tmac: man. (line 6) +* man.local <1>: Optional man extensions. + (line 6) +* man.local: Man usage. (line 6) +* man.tmac: man. (line 6) +* man.ultrix: Optional man extensions. + (line 30) +* nrchbar: Miscellaneous. (line 111) +* papersize.tmac: Paper Size. (line 16) +* perl: I/O. (line 171) +* pic: ms Insertions. (line 7) +* post-grohtml: Groff Options. (line 165) +* pre-grohtml: Groff Options. (line 165) +* refer: ms Insertions. (line 7) +* soelim: Debugging. (line 10) +* tbl: ms Insertions. (line 7) +* trace.tmac: Writing Macros. (line 101) +* troffrc <1>: Line Layout. (line 64) +* troffrc <2>: Troff and Nroff Mode. + (line 24) +* troffrc <3>: Manipulating Hyphenation. + (line 161) +* troffrc <4>: Paper Size. (line 16) +* troffrc: Groff Options. (line 80) +* troffrc-end <1>: Troff and Nroff Mode. + (line 24) +* troffrc-end <2>: Manipulating Hyphenation. + (line 161) +* troffrc-end: Groff Options. (line 80) +* tty.tmac: Troff and Nroff Mode. + (line 32) + + + +Local Variables: +coding: iso-8859-1 +End: |