diff options
Diffstat (limited to 'contrib/groff/doc/groff-8')
| -rw-r--r-- | contrib/groff/doc/groff-8 | 1416 |
1 files changed, 0 insertions, 1416 deletions
diff --git a/contrib/groff/doc/groff-8 b/contrib/groff/doc/groff-8 deleted file mode 100644 index 5217828d208c3..0000000000000 --- a/contrib/groff/doc/groff-8 +++ /dev/null @@ -1,1416 +0,0 @@ -This is groff, produced by makeinfo version 4.3d from ./groff.texinfo. - -This manual documents GNU `troff' version 1.19. - - Copyright (C) 1994-2000, 2001, 2002, 2003 Free Software Foundation, -Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover texts - being `A GNU Manual," and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - `GNU Free Documentation License." - - (a) The FSF's Back-Cover Text is: `You have freedom to copy and - modify this GNU Manual, like GNU software. Copies published by - the Free Software Foundation raise funds for GNU development." - -INFO-DIR-SECTION Typesetting -START-INFO-DIR-ENTRY -* Groff: (groff). The GNU troff document formatting system. -END-INFO-DIR-ENTRY - - -File: groff, Node: Warnings, Prev: Debugging, Up: Debugging - -Warnings --------- - - The warnings that can be given to `gtroff' are divided into the -following categories. The name associated with each warning is used by -the `-w' and `-W' options; the number is used by the `warn' request and -by the `.warn' register. - -`char' -`1' - Non-existent glyphs.(1) (*note Warnings-Footnote-1::) This is - enabled by default. - -`number' -`2' - Invalid numeric expressions. This is enabled by default. *Note - Expressions::. - -`break' -`4' - In fill mode, lines which could not be broken so that their length - was less than the line length. This is enabled by default. - -`delim' -`8' - Missing or mismatched closing delimiters. - -`el' -`16' - Use of the `el' request with no matching `ie' request. *Note - if-else::. - -`scale' -`32' - Meaningless scaling indicators. - -`range' -`64' - Out of range arguments. - -`syntax' -`128' - Dubious syntax in numeric expressions. - -`di' -`256' - Use of `di' or `da' without an argument when there is no current - diversion. - -`mac' -`512' - Use of undefined strings, macros and diversions. When an undefined - string, macro, or diversion is used, that string is automatically - defined as empty. So, in most cases, at most one warning is given - for each name. - -`reg' -`1024' - Use of undefined number registers. When an undefined number - register is used, that register is automatically defined to have a - value of 0. So, in most cases, at most one warning is given for - use of a particular name. - -`tab' -`2048' - Use of a tab character where a number was expected. - -`right-brace' -`4096' - Use of `\}' where a number was expected. - -`missing' -`8192' - Requests that are missing non-optional arguments. - -`input' -`16384' - Invalid input characters. - -`escape' -`32768' - Unrecognized escape sequences. When an unrecognized escape - sequence `\X' is encountered, the escape character is ignored, and - X is printed. - -`space' -`65536' - Missing space between a request or macro and its argument. This - warning is given when an undefined name longer than two characters - is encountered, and the first two characters of the name make a - defined name. The request or macro is not invoked. When this - warning is given, no macro is automatically defined. This is - enabled by default. This warning never occurs in compatibility - mode. - -`font' -`131072' - Non-existent fonts. This is enabled by default. - -`ig' -`262144' - Invalid escapes in text ignored with the `ig' request. These are - conditions that are errors when they do not occur in ignored text. - -`color' -`524288' - Color related warnings. - -`all' - All warnings except `di', `mac' and `reg'. It is intended that - this covers all warnings that are useful with traditional macro - packages. - -`w' - All warnings. - - -File: groff, Node: Warnings-Footnotes, Up: Warnings - - (1) `char' is a misnomer since it reports missing glyphs - there -aren't missing input characters, only invalid ones. - - -File: groff, Node: Implementation Differences, Prev: Debugging, Up: gtroff Reference - -Implementation Differences -========================== - - GNU `troff' has a number of features which cause incompatibilities -with documents written with old versions of `troff'. - - Long names cause some incompatibilities. UNIX `troff' interprets - - - .dsabcd - -as defining a string `ab' with contents `cd'. Normally, GNU `troff' -interprets this as a call of a macro named `dsabcd'. Also UNIX `troff' -interprets `\*[' or `\n[' as references to a string or number register -called `['. In GNU `troff', however, this is normally interpreted as -the start of a long name. In compatibility mode GNU `troff' interprets -long names in the traditional way (which means that they are not -recognized as names). - - - Request: .cp [n] - - Request: .do cmd - - Register: \n[.C] - If N is missing or non-zero, turn on compatibility mode; - otherwise, turn it off. - - The read-only number register `.C' is 1 if compatibility mode is - on, 0 otherwise. - - Compatibility mode can be also turned on with the `-C' command line - option. - - The `do' request turns off compatibility mode while executing its - arguments as a `gtroff' command. - - - .do fam T - - executes the `fam' request when compatibility mode is enabled. - - `gtroff' restores the previous compatibility setting before - interpreting any files sourced by the CMD. - - Two other features are controlled by `-C'. If not in compatibility -mode, GNU `troff' preserves the input level in delimited arguments: - - - .ds xx ' - \w'abc\*(xxdef' - -In compatibility mode, the string `72def'' is returned; without `-C' -the resulting string is `168' (assuming a TTY output device). - - Finally, the escapes `\f', `\H', `\m', `\M', `\R', `\s', and `\S' -are transparent for recognizing the beginning of a line only in -compatibility mode (this is a rather obscure feature). For example, -the code - - - .de xx - Hallo! - .. - \fB.xx\fP - -prints `Hallo!' in bold face if in compatibility mode, and `.xx' in -bold face otherwise. - - GNU `troff' does not allow the use of the escape sequences `\|', -`\^', `\&', `\{', `\}', `\<SP>', `\'', `\`', `\-', `\_', `\!', `\%', -and `\c' in names of strings, macros, diversions, number registers, -fonts or environments; UNIX `troff' does. The `\A' escape sequence -(*note Identifiers::) may be helpful in avoiding use of these escape -sequences in names. - - Fractional point sizes cause one noteworthy incompatibility. In -UNIX `troff' the `ps' request ignores scale indicators and thus - - - .ps 10u - -sets the point size to 10 points, whereas in GNU `troff' it sets the -point size to 10 scaled points. *Note Fractional Type Sizes::, for -more information. - - In GNU `troff' there is a fundamental difference between -(unformatted) input characters and (formatted) output glyphs. -Everything that affects how a glyph is output is stored with the glyph -node; once a glyph node has been constructed it is unaffected by any -subsequent requests that are executed, including `bd', `cs', `tkf', -`tr', or `fp' requests. Normally glyphs are constructed from input -characters at the moment immediately before the glyph is added to the -current output line. Macros, diversions and strings are all, in fact, -the same type of object; they contain lists of input characters and -glyph nodes in any combination. A glyph node does not behave like an -input character for the purposes of macro processing; it does not -inherit any of the special properties that the input character from -which it was constructed might have had. For example, - - - .di x - \\\\ - .br - .di - .x - -prints `\\' in GNU `troff'; each pair of input backslashes is turned -into one output backslash and the resulting output backslashes are not -interpreted as escape characters when they are reread. UNIX `troff' -would interpret them as escape characters when they were reread and -would end up printing one `\'. The correct way to obtain a printable -backslash is to use the `\e' escape sequence: This always prints a -single instance of the current escape character, regardless of whether -or not it is used in a diversion; it also works in both GNU `troff' and -UNIX `troff'.(1) (*note Implementation Differences-Footnote-1::) To -store, for some reason, an escape sequence in a diversion that will be -interpreted when the diversion is reread, either use the traditional -`\!' transparent output facility, or, if this is unsuitable, the new -`\?' escape sequence. - - *Note Diversions::, and *Note Gtroff Internals::, for more -information. - - -File: groff, Node: Implementation Differences-Footnotes, Up: Implementation Differences - - (1) To be completely independent of the current escape character, -use `\(rs' which represents a reverse solidus (backslash) glyph. - - -File: groff, Node: Preprocessors, Next: Output Devices, Prev: gtroff Reference, Up: Top - -Preprocessors -************* - - This chapter describes all preprocessors that come with `groff' or -which are freely available. - -* Menu: - -* geqn:: -* gtbl:: -* gpic:: -* ggrn:: -* grap:: -* grefer:: -* gsoelim:: - - -File: groff, Node: geqn, Next: gtbl, Prev: Preprocessors, Up: Preprocessors - -`geqn' -====== - -* Menu: - -* Invoking geqn:: - - -File: groff, Node: Invoking geqn, Prev: geqn, Up: geqn - -Invoking `geqn' ---------------- - - -File: groff, Node: gtbl, Next: gpic, Prev: geqn, Up: Preprocessors - -`gtbl' -====== - -* Menu: - -* Invoking gtbl:: - - -File: groff, Node: Invoking gtbl, Prev: gtbl, Up: gtbl - -Invoking `gtbl' ---------------- - - -File: groff, Node: gpic, Next: ggrn, Prev: gtbl, Up: Preprocessors - -`gpic' -====== - -* Menu: - -* Invoking gpic:: - - -File: groff, Node: Invoking gpic, Prev: gpic, Up: gpic - -Invoking `gpic' ---------------- - - -File: groff, Node: ggrn, Next: grap, Prev: gpic, Up: Preprocessors - -`ggrn' -====== - -* Menu: - -* Invoking ggrn:: - - -File: groff, Node: Invoking ggrn, Prev: ggrn, Up: ggrn - -Invoking `ggrn' ---------------- - - -File: groff, Node: grap, Next: grefer, Prev: ggrn, Up: Preprocessors - -`grap' -====== - - A free implementation of `grap', written by Ted Faber, is available -as an extra package from the following address: - - `http://www.lunabase.org/~faber/Vault/software/grap/' - - -File: groff, Node: grefer, Next: gsoelim, Prev: grap, Up: Preprocessors - -`grefer' -======== - -* Menu: - -* Invoking grefer:: - - -File: groff, Node: Invoking grefer, Prev: grefer, Up: grefer - -Invoking `grefer' ------------------ - - -File: groff, Node: gsoelim, Prev: grefer, Up: Preprocessors - -`gsoelim' -========= - -* Menu: - -* Invoking gsoelim:: - - -File: groff, Node: Invoking gsoelim, Prev: gsoelim, Up: gsoelim - -Invoking `gsoelim' ------------------- - - -File: groff, Node: Output Devices, Next: File formats, Prev: Preprocessors, Up: Top - -Output Devices -************** - -* Menu: - -* Special Characters:: -* grotty:: -* grops:: -* grodvi:: -* grolj4:: -* grolbp:: -* grohtml:: -* gxditview:: - - -File: groff, Node: Special Characters, Next: grotty, Prev: Output Devices, Up: Output Devices - -Special Characters -================== - - *Note Font Files::. - - -File: groff, Node: grotty, Next: grops, Prev: Special Characters, Up: Output Devices - -`grotty' -======== - -* Menu: - -* Invoking grotty:: - - -File: groff, Node: Invoking grotty, Prev: grotty, Up: grotty - -Invoking `grotty' ------------------ - - -File: groff, Node: grops, Next: grodvi, Prev: grotty, Up: Output Devices - -`grops' -======= - -* Menu: - -* Invoking grops:: -* Embedding PostScript:: - - -File: groff, Node: Invoking grops, Next: Embedding PostScript, Prev: grops, Up: grops - -Invoking `grops' ----------------- - - -File: groff, Node: Embedding PostScript, Prev: Invoking grops, Up: grops - -Embedding POSTSCRIPT --------------------- - - -File: groff, Node: grodvi, Next: grolj4, Prev: grops, Up: Output Devices - -`grodvi' -======== - -* Menu: - -* Invoking grodvi:: - - -File: groff, Node: Invoking grodvi, Prev: grodvi, Up: grodvi - -Invoking `grodvi' ------------------ - - -File: groff, Node: grolj4, Next: grolbp, Prev: grodvi, Up: Output Devices - -`grolj4' -======== - -* Menu: - -* Invoking grolj4:: - - -File: groff, Node: Invoking grolj4, Prev: grolj4, Up: grolj4 - -Invoking `grolj4' ------------------ - - -File: groff, Node: grolbp, Next: grohtml, Prev: grolj4, Up: Output Devices - -`grolbp' -======== - -* Menu: - -* Invoking grolbp:: - - -File: groff, Node: Invoking grolbp, Prev: grolbp, Up: grolbp - -Invoking `grolbp' ------------------ - - -File: groff, Node: grohtml, Next: gxditview, Prev: grolbp, Up: Output Devices - -`grohtml' -========= - -* Menu: - -* Invoking grohtml:: -* grohtml specific registers and strings:: - - -File: groff, Node: Invoking grohtml, Next: grohtml specific registers and strings, Prev: grohtml, Up: grohtml - -Invoking `grohtml' ------------------- - - -File: groff, Node: grohtml specific registers and strings, Prev: Invoking grohtml, Up: grohtml - -`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 - - - troff -Tps -rps4html=1 -dwww-image-template=TEMPLATE - - and secondly to - - - 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. - - The register `www-image-template' is set to the user specified - template name or the default name. - - -File: groff, Node: gxditview, Prev: grohtml, Up: Output Devices - -`gxditview' -=========== - -* Menu: - -* Invoking gxditview:: - - -File: groff, Node: Invoking gxditview, Prev: gxditview, Up: gxditview - -Invoking `gxditview' --------------------- - - -File: groff, Node: File formats, Next: Installation, Prev: Output Devices, Up: Top - -File formats -************ - - All files read and written by `gtroff' are text files. The -following two sections describe their format. - -* Menu: - -* gtroff Output:: -* Font Files:: - - -File: groff, Node: gtroff Output, Next: Font Files, Prev: File formats, Up: File formats - -`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:: - - -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 - -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 - -Separation -.......... - - 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 - -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 - -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 - -Command Reference ------------------ - - This section describes all intermediate output commands, both from -AT&T `troff' as well as the `gtroff' extensions. - -* Menu: - -* Comment Command:: -* Simple Commands:: -* Graphics Commands:: -* Device Control Commands:: -* Obsolete Command:: - - -File: groff, Node: Comment Command, Next: Simple Commands, Prev: Command Reference, Up: Command Reference - -Comment Command -............... - -`#ANYTHING<end of line>' - A comment. Ignore any characters from the `#' character up to the - next newline character. - - This command is the only possibility for commenting in the - intermediate output. Each comment can be preceded by arbitrary - syntactical space; every command can be terminated by a comment. - - -File: groff, Node: Simple Commands, Next: Graphics Commands, Prev: Comment Command, Up: Command Reference - -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: Simple Commands-Footnotes, Up: Simple Commands - - (1) `c' is actually a misnomer since it outputs a glyph. - - -File: groff, Node: Graphics Commands, Next: Device Control Commands, Prev: Simple Commands, Up: Command Reference - -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 - -Device Control Commands -....................... - - Each device control command starts with the letter `x', followed by -a space character (optional or arbitrary space or tab in `gtroff') and -a subcommand letter or word; each argument (if any) must be preceded by -a syntactical space. All `x' commands are terminated by a syntactical -line break; no device control command can be followed by another -command on the same line (except a comment). - - The subcommand is basically a single letter, but to increase -readability, it can be written as a word, i.e., an arbitrary sequence -of characters terminated by the next tab, space, or newline character. -All characters of the subcommand word but the first are simply ignored. -For example, `gtroff' outputs the initialization command `x i' as -`x init' and the resolution command `x r' as `x res'. - - In the following, the syntax element <line break> means a -syntactical line break (*note Separation::). - -`xF NAME<line break>' - The `F' stands for FILENAME. - - Use NAME as the intended name for the current file in error - reports. This is useful for remembering the original file name - when `gtroff' uses an internal piping mechanism. The input file is - not changed by this command. This command is a `gtroff' extension. - -`xf N S<line break>' - The `f' stands for FONT. - - Mount font position N (a non-negative integer) with font named S - (a text word). *Note Font Positions::. - -`xH N<line break>' - The `H' stands for HEIGHT. - - Set glyph height to N (a positive integer in scaled points `z'). - AT&T `troff' uses the unit points (`p') instead. *Note Output - Language Compatibility::. - -`xi<line break>' - The `i' stands for INIT. - - Initialize device. This is the third command of the prologue. - -`xp<line break>' - The `p' stands for PAUSE. - - Parsed but ignored. The 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 - -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: Intermediate Output Examples, Next: Output Language Compatibility, Prev: Command Reference, Up: gtroff Output - -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 - -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. - - * The classical quasi device independence is not yet implemented. - - * The old hardware was very different from what we use today. So the - `groff' devices are also fundamentally different from the ones in - AT&T `troff'. For example, the AT&T PostScript device is called - `post' and has a resolution of only 720 units per inch, suitable - for printers 20 years ago, while `groff''s `ps' device has a - resolution of 72000 units per inch. Maybe, by implementing some - rescaling mechanism similar to the classical quasi device - independence, `groff' could emulate AT&T's `post' device. - - * The B-spline command `D~' is correctly handled by the intermediate - output parser, but the drawing routines aren't implemented in some - of the postprocessor programs. - - * The argument of the commands `s' and `x H' has the implicit unit - scaled point `z' in `gtroff', while AT&T `troff' has point (`p'). - This isn't an incompatibility but a compatible extension, for both - units coincide for all devices without a `sizescale' parameter in - the `DESC' file, including all postprocessors from AT&T and - `groff''s text devices. The few `groff' devices with a - `sizescale' parameter either do not exist for AT&T `troff', have a - different name, or seem to have a different resolution. So - conflicts are very unlikely. - - * The position changing after the commands `Dp', `DP', and `Dt' is - illogical, but as old versions of `gtroff' used this feature it is - kept for compatibility reasons. - - - -File: groff, Node: Font Files, Prev: gtroff Output, Up: File formats - -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: - -* DESC File Format:: -* Font File Format:: - - -File: groff, Node: Font Files-Footnotes, Up: Font Files - - (1) Plan 9 `troff' has also abandoned the binary format. - |