diff options
Diffstat (limited to 'contrib/groff/man/groff_out.man')
| -rw-r--r-- | contrib/groff/man/groff_out.man | 2072 |
1 files changed, 1854 insertions, 218 deletions
diff --git a/contrib/groff/man/groff_out.man b/contrib/groff/man/groff_out.man index ae30f8d40474..5fe7dccefd34 100644 --- a/contrib/groff/man/groff_out.man +++ b/contrib/groff/man/groff_out.man @@ -1,251 +1,1887 @@ '\" e .\" The above line should force the use of eqn as a preprocessor .ig -Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc. +groff_out.5 -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +Last update: 12 Sep 2002 -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. +This file is part of groff, the GNU roff type-setting system. -Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be included in -translations approved by the Free Software Foundation instead of in -the original English. -.. -.\" This man page must be preprocessed with eqn. -.ie \n(.g .ds ic \/ -.el .ds ic \^ +Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc. +rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de> + +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 the +Invariant Sections being this .ig-section and AUTHORS, with no +Front-Cover Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +.. +. +.\" -------------------------------------------------------------------- +.\" Setup +.\" -------------------------------------------------------------------- +. +.mso www.tmac +. +.if n \{\ +. mso tty-char.tmac +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.if '\*[.T]'dvi' \ +. ftr CB CW +. +.if t \{\ +.EQ +delim $$ +.EN +.\} +. +.\" ----------------- Document configuration +. +.\" Number register to decide whether the commands `{' and `}' are used +.\" 0: disable (actual default); 1: enable +.nr @USE_ENV_STACK 0 +. +.ig +Unfortunately, old versions of groff used an illogical position change +after some D\~commands (Dp, DP, Dt). If the number register +@STUPID_DRAWING_POSITIONING is 1 (actual default) then change position +after these commands, otherwise the position is not changed. +.. +.nr @STUPID_DRAWING_POSITIONING 1 +. +.\" ----------------- Syntactical definitions +. +.\" comments when escapes are switched off +.de c +.. +.\" Begin of macro definitions +.eo +. +.de Text +. nop \)\$* +.. +.c follow-up line for a .TP header +.de TP+ +. br +. ns +. TP \$1 +.. +.c a bulleted paragraph +.de Topic +. TP 2m +. nop \[bu] +.. +.de ShellCommand +. br +. IR "shell>" "\h'1m'\f[CB]\$*\f[]\/" +.. +.ec +.\" End of macro definitions +. +.c ----------------- Semantical definitions +. +.nr @maxcolor 65536 +.ds @backslash \[rs]\" +.ds @linebreak \f[R]\[la]line_break\[ra]\f[]\" +. +.\" Begin of macro definitions +.eo +. +.c format: .unit <letter> <punctuation> +.de unit +. BR \$@ +.. +.c argument in italic with punctuation +.de argument +. if (\n[.$] == 0) \ +. return +. IR \$@ +.. +.c comma separated list of indexed variables +.de list1..n +. ds @arg1 \$1\" +. nop \c +. ie t \ +. nop $\*[@arg1] sub 1$, $\*[@arg1] sub 2$, .\|.\|., $\*[@arg1] sub n$ \c +. el \{\ +. IR \*[@arg1]1 , +. IR \*[@arg1]2 , +. nop \&..., +. I \*[@arg1]n +. \} +. rm @arg1 +.. +.de offset +. if (\n[.$] < 2) \ +. ab `.offset' needs at least 2 arguments +. ds @arg1 \$1\" +. ds @arg2 \$2\" +. shift 2 +. nop (\f[I]\,\*[@arg1]\/\f[],\ \f[I]\,\*[@arg2]\/\f[])\$* +. rm @arg1 +. rm @arg2 +.. +.de indexed_offset +. if (\n[.$] < 4) \ +. ab `.indexed_offset' needs at least 4 arguments +. ds @arg1 \$1\" +. ds @index1 \$2\" +. ds @arg2 \$3\" +. ds @index2 \$4\" +. shift 4 +. ie t \{\ +. ie \B'\*[@index1]' \{\ +. nop ($\*[@arg1] sub roman \*[@index1]$,\ \c +. \} +. el \{\ +. nop ($\*[@arg1] sub \*[@index1]$,\ \c +. \} +. ie \B'\*[@index2]' \{\ +. nop $\*[@arg2] sub roman \*[@index2]$)\$* \c +. \} +. el \{\ +. nop $\*[@arg2] sub \*[@index2]$)\$* \c +. \} +. \} +. el \{\ +. nop (\f[I]\*[@arg1]\*[@index1]\f[],\ \c +. nop \f[I]\*[@arg2]\*[@index2]\f[])\$* \c +. \} +. rm @arg1 +. rm @arg2 +. rm @index1 +. rm @index2 +.. +.c format: .command <name> "<arguments>" <punctuation> +.de command +. ds @arg1 \$1\" +. ds @arg2 \$2\" +. shift 2 +. IP "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*" +. rm @arg1 +. rm @arg2 +.. +.c format: .command+ <name> "<arguments>" <punctuation> +.c continue previous .command heading +.de command+ +. ds @arg1 \$1\" +. ds @arg2 \$2\" +. shift 2 +. TP+ +. Text "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*" +. rm @arg1 +. rm @arg2 +.. +.c format: .D-command <subcommand> "<arguments>" +.de D-command +. ds @sub \$1\" +. shift 1 +. IP "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\|\*[@linebreak]" +. rm @sub +.. +.c format: .D-command+ <subcommand> "<arguments>" +.c continue previous .D-command heading +.de D-command+ +. ds @sub \$1\" +. shift 1 +. TP+ +. Text "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\*[@linebreak]" +. rm @sub +.. +.de Da-command +. shift 1 +. ie t \ +. ds @args $h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$\" +. el \ +. ds @args \f[I]h1\~v1 h2\~v2\f[]\" +. IP "\f[B]Da\f[]\ \*[@args]\|\*[@linebreak]" +. rm @args +.. +.c graphics command .D with a variable number of arguments +.c format: .D-multiarg <subcommand> +.de D-multiarg +. ds @sub \$1\" +. shift 1 +. ie t \{\ +. ds @args "$h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$ .\|.\|. \" +. as @args "$h sub n$\~$v sub n$\" +. \} +. el \ +. ds @args \f[I]h1\~v1 h2\~v2\f[] ... \f[I]\,hn\~vn\f[]\" +. IP "\f[B]D\*[@sub]\f[]\ \*[@args]\|\*[@linebreak]" +. rm @args +. rm @sub +.. +.c format: .x-command <subname> "<arguments>" +.de x-command +. ds @sub \$1\" +. shift 1 +. ds @args +. if (\n[.$] > 0) \ +. ds @args \ \f[I]\,\$*\/\f[]\" +. IP "\f[B]x\*[@sub]\f[]\*[@args]\f[]\|\*[@linebreak]" +. rm @sub +. rm @args +.. +.de xsub +. RI "(" "\$1" " control command)" +. br +.. +.ec +.\" End of macro definitions +. +. +.\" -------------------------------------------------------------------- +.\" Title +.\" -------------------------------------------------------------------- +. .TH GROFF_OUT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@" +. .SH NAME groff_out \- groff intermediate output format +. +. +.\" -------------------------------------------------------------------- .SH DESCRIPTION -This manual page describes the format output by GNU troff. -The output format used by GNU troff is very similar to that used -by Unix device-independent troff. Only the differences are documented -here. -.LP -The argument to the -.B s -command is in scaled points (units of -.IR points/ n , -where -.I n -is the argument to the -.B sizescale -command in the DESC file.) -The argument to the -.B x\ Height -command is also in scaled points. -.LP -The first three output commands are guaranteed to be: -.IP -.BI x\ T\ device +.\" -------------------------------------------------------------------- +. +This manual page describes the intermediate output format of the GNU +.BR roff (@MAN7EXT@) +text processing system. +. +This output is produced by a run of the GNU +.BR troff (@MAN1EXT@) +program before it is fed into a device postprocessor program. +. +.P +As the GNU roff processor +.BR groff (@MAN1EXT@) +is a wrapper program around troff that automatically calls a +postprocessor, this output does not show up normally. +. +This is why it is called +.I intermediate +within the +.I groff +.IR system . +. +The +.B groff +program provides the option +.B -Z +to inhibit postprocessing, such that the produced intermediate output +is sent to standard output just like calling +.B troff +manually. +. +.P +In this document, the term +.I troff output +describes what is output by the GNU troff program, while +.I 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. +. +The pre-groff roff versions are denoted as +.I classical +.IR troff . +. +.P +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 +.BR groff (@MAN7EXT@) +language. +. +While the +.I groff +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. +. +.P +The intermediate output produced by +.I groff +is fairly readable, while +.I classical troff +output was hard to understand because of strange habits that are +still supported, but not used any longer by +.I GNU +.IR troff . +. +. +.\" -------------------------------------------------------------------- +.SH "LANGUAGE CONCEPTS" +.\" -------------------------------------------------------------------- +. +During the run of +.BR troff , +the roff input 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 or without arguments. +. +In this document, the term "command" always refers to the intermediate +output language, never to the roff language used for document +formatting. +. +There are commands for positioning and text writing, for drawing, and +for device controlling. +. +. +.\" -------------------------------------------------------------------- +.SS "Separation" +.\" -------------------------------------------------------------------- +. +.I Classical troff output +had strange requirements on whitespace. +. +The +.I groff +output parser, however, is smart about whitespace by making it +maximally optional. +. +The whitespace characters, i.e.\& the +.IR tab , +.IR space , +and +.I newline +characters, always have a syntactical meaning. +. +They are never printable because spacing within the output is always +done by positioning commands. +. +.P +Any sequence of +.I space +or +.I tab +characters is treated as a single +.B syntactical +.BR 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. +. +.P +A line break is a syntactical element, too. +. +Every command argument can be followed by whitespace, a comment, or a +newline character. +. +Thus a +.B syntactical line break +is defined to consist of optional syntactical space that is optionally +followed by a comment, and a newline character. +. +.P +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 groff intermediate output, every +command with at least one argument is followed by a line break, thus +providing excellent readability. +. +.P +The other commands \[em] those for drawing and device controlling \[em] +have a more complicated structure; some recognize long command names, +and some take a variable number of arguments. +. +So all +.B D +and +.B x +commands were designed to request a +.I syntactical line break +after their last argument. +. +Only one command, +.RB ` 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. +. +.P +Empty lines, i.e.\& lines containing only space and/or a comment, can +occur everywhere. +. +They are just ignored. +. +. +.\" -------------------------------------------------------------------- +.SS "Argument Units" +.\" -------------------------------------------------------------------- +. +Some commands take integer arguments that are assumed to represent +values in a measurement unit, but the letter for the corresponding +.I scale indicator +is not written with the output command arguments; see +.BR groff (@MAN7EXT@) +and the groff info file for more on this topic. +. +Most commands assume the scale indicator\~\c +.unit u , +the basic unit of the device, some use\~\c +.unit z , +the +.I scaled point unit +of the device, while others, such as the color commands expect plain +integers. +. +Note that these scale indicators are relative to the chosen device. +. +They are defined by the parameters specified in the device's +.I DESC +file; see +.BR groff_font (@MAN5EXT@). +. +.P +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. +. +.P +A string argument is always terminated by the next whitespace +character (space, tab, or newline); an embedded +.B # +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. +. +. +.\" -------------------------------------------------------------------- +.SS "Document Parts" +.\" -------------------------------------------------------------------- +A correct intermediate output document consists of two parts, the +prologue and the body. +. +.P +The task of the +.I prologue +is to set the general device parameters using three exactly specified +commands. +. +The +.I groff prologue +is guaranteed to consist of the following three lines (in that order): +.RS +.P +.B x\ T +.I device .br -.BI x\ res\ n\ h\ v +.B x\ res +.I n\ h\ v .br .B x init -.LP -If the -.B tcommand -line is present in the DESC file, troff will use the following -two commands -.TP -.BI t xxx -.I xxx -is any sequence of characters terminated by a space or a newline; -the first character should be printed at the current position, -the the current horizontal position should be increased by -the width of the first character, and so on for each character. -The width of the character is that given in the font file, -appropriately scaled for the current point size, and rounded -so that it is a multiple of the horizontal resolution. -Special characters cannot be printed using this command. +.RE +.P +with the arguments set as outlined in the section +.BR "Device Control Commands" . +. +But the parser for the intermediate output format is able to swallow +additional whitespace and comments as well. +. +.P +The +.I 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 +.B x\ stop +command is encountered; the last line of any groff intermediate output +always contains such a command. +. +.P +Semantically, the body is page oriented. +. +A new page is started by a +.BR p \~command. +. +Positioning, writing, and drawing commands are always done within the +current page, so they cannot occur before the first +.BR p \~command. +. +Absolute positioning (by the +.B H +and +.BR V \~commands) +is done relative to the current page, all other positioning +is done relative to the current location within this page. +. +. +.\" -------------------------------------------------------------------- +.SH "COMMAND REFERENCE" +.\" -------------------------------------------------------------------- +. +This section describes all intermediate output commands, the classical +commands as well as the +.I groff +extensions. +. +. +.\" -------------------------------------------------------------------- +.SS "Comment Command" +.\" -------------------------------------------------------------------- +. .TP -.BI u n\ xxx -This is same as the +.BI # anything \[la]end_of_line\[ra] +A comment. +. +Ignore any characters from the +.BR # \~\c +character up to the next newline character. +. +.P +This command is the only possibility for commenting in the intermediate +output. +. +Each comment can be preceded by arbitrary +.I syntactical +.IR space ; +every command can be terminated by a comment. +. +. +.\" -------------------------------------------------------------------- +.SS "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, +.I 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. +. +. +.if (\n[@USE_ENV_STACK] == 1) \{\ +.command { +Open a new environment by copying the actual device configuration data +to the environment stack. +. +The current environment is setup by the device specification and +manipulated by the setting commands. +. +. +.command } +Close the actual environment (opened by a preceding +.BR { \~command) +and restore the previous environment from the environment +stack as the actual device configuration data. +. +\} \" endif @USE_ENV_STACK +. +. +.command C xxx \[la]white_space\[ra] +Print a special groff character named +.argument xxx . +. +The trailing syntactical space or line break is necessary to allow +character names of arbitrary length. +. +The character is printed at the current print position; +the character's size is read from the font file. +. +The print position is not changed. +. +. +.command c c +Print character\~\c +.argument c +at the current print position; +the character's size is read from the font file. +. +The print position is not changed. +. +. +.command f n +Set font to font number\~\c +.argument n +(a non-negative integer). +. +. +.command H n +Move right to the absolute vertical position\~\c +.argument n +(a non-negative integer in basic units\~\c +.unit u ) +relative to left edge of current page. +. +. +.command h n +Move +.argument n +(a non-negative integer) basic units\~\c +.unit u +horizontally to the right. +. +.I [54] +allows negative values for +.I n +also, but +.I groff +doesn't use this. +. +. +.command m "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]" +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 +.BR DF . +. +The color components are specified as integer arguments between 0 and +\n[@maxcolor]. +. +The number of color components and their meaning vary for the +different color schemes. +. +These commands are generated by the groff escape sequence +.BR \*[@backslash]m . +. +No position changing. +. +These commands are a groff extension. +. +. +.RS +. +.command mc "cyan magenta yellow" +Set color using the CMY color scheme, having the 3\~color components +cyan, magenta, and yellow. +. +. +.command md +Set color to the default color value +(black in most cases). +. +No component arguments. +. +. +.command mg "gray" +Set color to the shade of gray given by the argument, an integer +between 0 (black) and \n[@maxcolor] (white). +. +. +.command mk "cyan magenta yellow black" +Set color using the CMYK color scheme, having the 4\~color components +cyan, magenta, yellow, and black. +. +.command mr "red green blue" +Set color using the RGB color scheme, having the 3\~color components +red, green, and blue. +. +.RE +. +. +.command N n +Print character with index\~\c +.argument n +(a non-negative integer) of the current font. +. +The print position is not changed. +. +This command is a groff extension. +. +. +.command n b\ a +Inform the device about a line break, but no positioning is done by +this command. +. +In classical troff, the integer arguments +.argument b +and\~\c +.argument 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. +. +. +.command p n +Begin a new page in the outprint. +. +The page number is set to\~\c +.argument 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 +.BR p \~command +must be issued before any of these commands. +. +. +.command s n +Set point size to +.argument n +scaled points +(this is unit\~\c +.unit z +in GNU +.BR troff ). +. +Classical troff used the unit +.I points +(\c +.unit p ) +instead; see section +.BR COMPATIBILITY . +. +. +.command t xxx \[la]white_space\[ra] +.command+ t "xxx dummy_arg" \[la]white_space\[ra] +Print a word, i.e.\& a sequence of characters +.argument xxx +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 character should be printed at the current position, the +current horizontal position should then be increased by the width of +the first character, and so on for each character. +. +The widths of the characters 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 +.B C +command for named characters). +. +This command is a groff extension; it is only used for devices whose +.I DESC +file contains the +.B tcommand +keyword; see +.BR groff_font (@MAN5EXT@). +. +. +.command u "n xxx" \[la]white_space\[ra] +Print word with track kerning. +. +This is the same as the .B t -command except that after printing each character, the current horizontal -position is increased by the sum of the width of that character +command except that after printing each character, the current +horizontal position is increased by the sum of the width of that +character and\~\c +.argument n +(an integer in +basic units\~\c +.unit u ). +This command is a groff extension; it is only used for devices whose +.I DESC +file contains the +.B tcommand +keyword; see +.BR groff_font (@MAN5EXT@). +. +. +.command V n +Move down to the absolute vertical position\~\c +.argument n +(a non-negative integer in basic units\~\c +.unit u ) +relative to upper edge of current page. +. +. +.command v n +Move +.argument n +basic units\~\c +.unit u +down +.RI ( n +is a non-negative integer). +. +.I [54] +allows negative values for +.I n +also, but +.I groff +doesn't use this. +. +. +.command w +Informs about a paddable whitespace to increase readability. +. +The spacing itself must be performed explicitly by a move command. +. +. +.\" -------------------------------------------------------------------- +.SS "Graphics Commands" +.\" -------------------------------------------------------------------- +. +Each graphics or drawing command in the intermediate output starts +with the letter\~\c +.B 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 +.BR D \ command +may not be followed by another command on the same line +(apart from a comment), so each +.BR D \ command +is terminated by a syntactical line break. +. +.P +.I troff +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. +. +.P +Some graphics commands can take a variable number of arguments. +. +In this case, they are integers representing a size measured in basic +units\~\c +.unit u . +. +The arguments called +.list1..n h +stand for horizontal distances where positive means right, negative +left. +. +The arguments called +.list1..n v +stand for vertical distances where positive means down, negative up. +. +All these distances are offsets relative to the current location. +. +.P +Unless indicated otherwise, each graphics command directly corresponds +to a similar +.I groff +.B \*[@backslash]D +escape sequence; see +.BR groff (@MAN7EXT@). +. +.P +Unknown D\~commands are assumed to be device-specific. +. +Its arguments are parsed as strings; the whole information is then +sent to the postprocessor. +. +.P +In the following command reference, the syntax element +.I \[la]line_break\[ra] +means a +.I syntactical line break +as defined in section +.BR Separation . +. +. +.D-multiarg ~ +Draw B-spline from current position to offset +.indexed_offset h 1 v 1 , +then to offset +.indexed_offset h 2 v 2 +if given, etc.\& up to +.indexed_offset h n v n . +This command takes a variable number of argument pairs; +the current position is moved to the terminal point of the drawn curve. +. +. +.Da-command +Draw arc from current position to +.indexed_offset h 1 v 1 \|+\|\c +.indexed_offset h 2 v 2 +with center at +.indexed_offset h 1 v 1 ; +then move the current position to the final point of the arc. +. +. +.D-command C d +.D-command+ C d dummy_arg +Draw a solid circle using the current fill color with diameter\~\c +.argument d +(integer in basic units\~\c +.unit 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 to the +formatter to generate an even number of arguments). +. +This command is a groff extension. +. +. +.D-command c d +Draw circle line with diameter\~\c +.argument d +(integer in basic units\~\c +.unit u ) +with leftmost point at the current position; then move the current +position to the rightmost point of the circle. +. +. +.D-command E "h v" +Draw a solid ellipse in the current fill color with a horizontal +diameter of\~\c +.argument h +and a vertical diameter of\~\c +.argument v +(both integers in basic units\~\c +.unit u ) +with the leftmost point at the current position; then move to the +rightmost point of the ellipse. +. +This command is a groff extension. +. +. +.D-command e "h v" +Draw an outlined ellipse with a horizontal diameter of\~\c +.argument h +and a vertical diameter of\~\c +.argument v +(both integers in basic units\~\c +.unit u ) +with the leftmost point at current position; then move to the +rightmost point of the ellipse. +. +. +.D-command F "color_scheme \f[R][\f[]component .\|.\|.\f[R]]\f[]" +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 +.BR m . +. +The color components are specified as integer arguments between 0 and +\n[@maxcolor]. +. +The number of color components and their meaning vary for the +different color schemes. +. +These commands are generated by the groff escape sequences +.B \*[@backslash]D'F\ .\|.\|.' and -.IR n . -.LP -Note that single characters can have the eighth bit set, as can the -names of fonts and special characters. -.LP -The names of characters and fonts can be of arbitrary length; drivers -should not assume that they will be only two characters long. -.LP -When a character is to be printed, that character will always be -in the current font. -Unlike device-independent troff, it is not necessary -for drivers to search special fonts to find a character. -.LP -The -.B x -device control command has been extended. +.B \*[@backslash]M +(with no other corresponding graphics commands). +. +No position changing. +. +This command is a groff extension. +. +. +.RS +. +.D-command Fc "cyan magenta yellow" +Set fill color for solid drawing objects using the CMY color scheme, +having the 3\~color components cyan, magenta, and yellow. +. +. +.D-command Fd +Set fill color for solid drawing objects to the default fill color value +(black in most cases). +. +No component arguments. +. +. +.D-command Fg "gray" +Set fill color for solid drawing objects to the shade of gray given by +the argument, an integer between 0 (black) and \n[@maxcolor] (white). +. +. +.D-command Fk "cyan magenta yellow black" +Set fill color for solid drawing objects using the CMYK color scheme, +having the 4\~color components cyan, magenta, yellow, and black. +. +.D-command Fr "red green blue" +Set fill color for solid drawing objects using the RGB color scheme, +having the 3\~color components red, green, and blue. +. +.RE +. +. +.D-command f n +The argument +.argument n +must be an integer in the range -32767 to 32767. +. +.RS .TP -\fBx u \fIn\fR -If -.I n -is\~1, start underlining of spaces. +.RI "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 +.BR DFg . +. +.TP +.IR 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 +.BR m . +For example, the command sequence +. +.nf +.ft CB +.RS +.RS +mg 0 0 \n[@maxcolor] +Df -1 +.RE +.ft +.fi +. +sets all colors to blue. +.RE +. +.P +No position changing. +. +This command is a groff extension. +. +.RE +. +. +.D-command l "h v" +Draw line from current position to offset +.offset h v +(integers in basic units\~\c +.unit u ); +then set current position to the end of the drawn line. +. +. +.D-multiarg p +Draw a polygon line from current position to offset +.offset h1 v1 , +from there to offset +.offset h2 v2 , +etc.\& up to offset +.offset hn vn , +and from there back to the starting position. +. +.ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\ +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. +. +\} +.el \{\ +As the polygon is closed, the end of drawing is the starting point, so +the position doesn't change. +\} +. +This command is a groff extension. +. +. +.D-multiarg P +The same macro as the corresponding +.B Dp +command with the same arguments, but draws a solid polygon in the +current fill color rather than an outlined polygon. +. +.ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\ +The position is changed in the same way as with +.BR Dp . +\} +.el \ +No position changing. +. +This command is a groff extension. +. +. +.D-command t n +Set the current line thickness to\~\c +.argument n +(an integer in basic units\~\c +.unit u ) +if +.argument n >0; +if +.argument n =0 +select the smallest available line thickness; if +.argument n <0 +set the line thickness proportional to the point size (this is the +default before the first +.B Dt +command was specified). +. +.ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\ +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. +. +\} +.el \ +No position changing. +. +This command is a groff extension. +. +. +.\" -------------------------------------------------------------------- +.SS "Device Control Commands" +.\" -------------------------------------------------------------------- +. +Each device control command starts with the letter +.B x +followed by a space character (optional or arbitrary space/\:tab in +groff) and a subcommand letter or word; each argument (if any) must be +preceded by a syntactical space. +. +All +.B x +commands are terminated by a +.IR "syntactical line break" ; +no device control command can be followed by another command on the same +line (except a comment). +. +.P +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, +.I troff +outputs the initialization command +.B x\ i +as +.B x\ init +and the resolution command +.B x\ r +as +.BR "x\ res" . +. +But writings like +.B x\ i_like_groff +and +.B x\ roff_is_groff +resp.\& are accepted as well to mean the same commands. +. +.P +In the following, the syntax element +.I \[la]line_break\[ra] +means a +.I syntactical line break +as defined in section +.BR Separation . +. +.x-command F name +.xsub Filename +Use +.argument name +as the intended name for the current file in error reports. +. +This is useful for remembering the original file name when groff uses +an internal piping mechanism. +. +The input file is not changed by this command. +. +This command is a groff extension. +. +. +.x-command f "n\ s" +.xsub font +Mount font position\~\c +.argument n +(a non-negative integer) with font named\~\c +.argument s +(a text word), +cf. +.BR groff_font (@MAN5EXT@). +. +. +.x-command H n +.xsub Height +Set character height to\~\c +.argument n +(a positive integer in scaled points\~\c +.unit z ). +. +Classical troff used the unit +points (\c +.unit p ) +instead; see section +.BR COMPATIBILITY . +. +. +.x-command i +.xsub init +Initialize device. +. +This is the third command of the prologue. +. +. +.x-command p +.xsub pause +Parsed but ignored. +. +The classical documentation reads +.I pause device, can be +.IR restarted . +. +. +.x-command r "n\ h\ v" +.xsub resolution +Resolution is\~\c +.argument n , +while +.argument h +is the minimal horizontal motion, and +.argument v +the minimal vertical motion possible with this device; all arguments +are positive integers in basic units\~\c +.unit u +per inch. +. +This is the second command of the prologue. +. +. +.x-command S n +.xsub Slant +Set slant to\~\c +.argument n +(an integer in basic units\~\c +.unit u ). +. +. +.x-command s +.xsub stop +Terminates the processing of the current file; issued as the last +command of any intermediate troff output. +. +. +.x-command t +.xsub trailer +Generate trailer information, if any. +. +In +.IR groff , +this is actually just ignored. +. +. +.x-command T xxx +.xsub Typesetter +Set name of device to word +.argument xxx , +a sequence of characters ended by the next whitespace character. +. +The possible device names coincide with those from the groff +.B -T +option. +. +This is the first command of the prologue. +. +. +.x-command u n +.xsub underline +Configure underlining of spaces. +. If -.I n +.argument n +is\~1, start underlining of spaces; +if +.argument n is\~0, stop underlining of spaces. +. This is needed for the .B cu -request in nroff mode and is ignored otherwise. -.LP +request in +.I nroff +mode and is ignored otherwise. +. +This command is a groff extension. +. +. +.x-command X anything +.xsub X-escape +Send string +.argument anything +uninterpreted to the device. +. +If the line following this command starts with a +.B + +character this line is interpreted as a continuation line in the +following sense. +. +The +.B + +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 +.B + +character. +. +This command is generated by the +.I groff +escape sequence +.BR \*[@backslash]X . +. +The line-continuing feature is a groff extension. +. +. +.\" -------------------------------------------------------------------- +.SS "Obsolete Command" +.\" -------------------------------------------------------------------- +. +In +.I classical troff +output, the writing of a single character was mostly done by a very +strange command that combined a horizontal move and the printing of a +character. +. +It didn't have a command code, but is represented by a 3-character +argument consisting of exactly 2\~digits and a character. +. +.TP +.argument ddc +Move right +.argument dd +(exactly two decimal digits) basic units\~\c +.unit u , +then print character\~\c +.argument c . +. +.RS +.P +In groff, 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 +.I classical +.IR troff , +large clusters of these and other commands were used, mostly without +spaces; this made such output almost unreadable. +. +.RE +. +.P +For modern high-resolution devices, this command does not make sense +because the width of the characters can become much larger than two +decimal digits. +. +In groff, this is only used for the devices +.BR X75 , +.BR X75-12 , +.BR X100 , +and +.BR X100-12 . +. +For other devices, +the commands +.B t +and\~\c +.B u +provide a better functionality. +. +. +.\" -------------------------------------------------------------------- +.SH "POSTPROCESSING" +.\" -------------------------------------------------------------------- +. +The +.I roff +postprocessors are programs that have the task to translate the +intermediate output into actions that are sent to a device. +. +A device can be some piece of hardware such as a printer, or a software +file format suitable for graphical or text processing. +. +The +.I groff +system provides powerful means that make the programming of such +postprocessors an easy task. +.P +There is a library function that parses the intermediate output and +sends the information obtained to the device via methods of a class +with a common interface for each device. +. +So a +.I groff +postprocessor must only redefine the methods of this class. +. +For details, see the reference in section +.BR FILES . +. +. +.\" -------------------------------------------------------------------- +.SH "EXAMPLES" +.\" -------------------------------------------------------------------- +. +This section presents the intermediate output generated from the same +input for three different devices. +. +The input is the sentence +.I hell world +fed into groff on the command line. +. +.Topic +High-resolution device +.I ps +. +.RS +. +.P +.ShellCommand echo "hell world" | groff -Z -T ps +. +.P +.nf +.ft CB +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 +.ft P +.fi +.RE +. +.P +This output can be fed into the postprocessor +.BR grops (@MAN1EXT@) +to get its representation as a PostScript file. +. +. +.Topic +Low-resolution device +.I latin1 +. +.RS +. +.P +This is similar to the high-resolution device except that the +positioning is done at a minor scale. +. +Some comments (lines starting with +.IR # ) +were added for clarification; they were not generated by the +formatter. +. +.P +.ShellCommand echo "hell world" | groff -Z -T latin1 +. +.P +.nf +.I # prologue +.ft CB +x T latin1 +x res 240 24 40 +x init +.I # begin a new page +.ft CB +p1 +.I # font setup +.ft CB +x font 1 R +f1 +s10 +.I # initial positioning on the page +.ft CB +V40 +H0 +.I # write text `hell' +.ft CB +thell +.I # inform about a space, and do it by a horizontal jump +.ft CB +wh24 +.I # write text `world' +.ft CB +tworld +.I # announce line break, but do nothing because ... +.ft CB +n40 0 +.I # ... the end of the document has been reached +.ft CB +x trailer +V2640 +x stop +.ft P +.fi +.RE +. +.P +This output can be fed into the postprocessor +.BR grotty (@MAN1EXT@) +to get a formatted text document. +. +. +.Topic +Classical style output +. +.RS +. +.P +As a computer monitor has a very low resolution compared to modern +printers the intermediate output for the X\~devices can use the +jump-and-write command with its 2-digit displacements. +. +.P +.ShellCommand echo "hell world" | groff -Z -T X100 +. +.P +.nf +.ft CB +x T X100 +x res 100 1 1 +x init +p1 +x font 5 TR +f5 +s10 +V16 +H100 +.I # write text with old-style jump-and-write command +.ft CB +ch07e07l03lw06w11o07r05l03dh7 +n16 0 +x trailer +V1100 +x stop +.ft P +.fi +.RE +. +.P +This output can be fed into the postprocessor +.BR xditview (1x) +or +.BR gxditview (@MAN1EXT@) +for displaying in\~X. +. +.P +Due to the obsolete jump-and-write command, the text clusters in the +classical output are almost unreadable. +. +. +.\" -------------------------------------------------------------------- +.SH "COMPATIBILITY" +.\" -------------------------------------------------------------------- +. +The intermediate output language of the +.I classical troff +was first documented in +.IR [97] . +. The +.I groff +intermediate output format is compatible with this specification +except for the following features. +.Topic +The classical quasi device independence is not yet implemented. +. +.Topic +The old hardware was very different from what we use today. +. +So the groff devices are also fundamentally different from the ones in +classical troff. +. +For example, the classical PostScript device was called +.I post +and had a resolution of 720 units per inch, +while groff's +.I ps +device has a resolution of 72000 units per inch. +. +Maybe, by implementing some rescaling mechanism similar to the +classical quasi device independence, these could be integrated into +modern groff. +. +.Topic +The B-spline command +.B D~ +is correctly handled by the intermediate output parser, but the +drawing routines aren't implemented in some of the postprocessor +programs. +.Topic +The argument of the commands +.B s +and +.B x H +has the implicit unit scaled point\~\c +.unit z +in groff, while classical troff had point (\c +.unit p ). +. +This isn't an incompatibility, but a compatible extension, +for both units coincide for all devices without a +.I sizescale +parameter, including all classical and the groff text devices. +. +The few groff devices with a sizescale parameter either did +not exist, had a different name, or seem to have had a different +resolution. +. +So conflicts with classical devices are very unlikely. +. +.ie (\n[@STUPID_DRAWING_POSITIONING] == 1) \{\ +.Topic +The position changing after the commands +.BR Dp , +.BR DP , +and +.B Dt +is illogical, but as old versions of groff used this feature it is +kept for compatibility reasons. +.\} \" @STUPID_DRAWING_POSITIONING +.el \{\ +.Topic +Temporarily, there existed some confusion on the positioning after the .B D -drawing command has been extended. -These extensions will not be used by GNU pic if the -.B \-n -option is given. +commands that are groff extensions. +. +This has been clarified by establishing the classical rule for all +groff drawing commands: +. +.RS +.P +.I The position after a graphic object has been drawn is at its end; +.I for circles and ellipses, the "end" is at the right side. +.RE +. +.P +From this, the positionings specified for the drawing commands above +follow quite naturally. +.\} \" @STUPID_DRAWING_POSITIONING +. +.P +The differences between groff and classical troff are documented in +.BR groff_diff (@MAN7EXT@). +. +. +.\" -------------------------------------------------------------------- +.SH "FILES" +.\" -------------------------------------------------------------------- +. .TP -\fBDf \fIn\fR\*(ic\en -Set the shade of gray to be used for filling solid objects to -.IR n ; -.I 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 will be used. -Whatever color a solid object has, it should completely obscure -everything beneath it. -A value greater than 1000 or less than 0 can also be used: -this means fill with the shade of gray that is currently being used -for lines and text. -Normally this will be black, but some drivers may provide -a way of changing this. +.BI @FONTDIR@/dev name /DESC +Device description file for device +.IR name . +. .TP -\fBDC \fId\fR\*(ic\en -Draw a solid circle with a diameter of -.I d -with the leftmost point at the current position. +.IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cc +Defines the parser and postprocessor for the intermediate output. +. +It is located relative to the top directory of the +.I groff +source tree, e.g. +.IR @GROFFSRCDIR@ . +. +This parser is the definitive specification of the +.I groff +intermediate output format. +. +. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +. +A reference like +.BR groff (@MAN7EXT@) +refers to a manual page; here +.I groff +in section\~\c +.I @MAN7EXT@ +of the man-page documentation system. +. +To read the example, look up section\~@MAN7EXT@ in your desktop help +system or call from the shell prompt +. +.RS +.P +.ShellCommand man @MAN7EXT@ groff +.RE +. +.P +For more details, see +.BR man (1). +. .TP -\fBDE \fIdx dy\fR\*(ic\en -Draw a solid ellipse with a horizontal diameter of -.I dx -and a vertical diameter of -.I dy -with the leftmost point at the current position. -.EQ -delim $$ -.EN +.BR groff (@MAN1EXT@) +option +.B -Z +and further readings on groff. +. .TP -\fBDp\fR $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\en -Draw a polygon with, -for $i = 1 ,..., n+1$, the -.IR i -th -vertex at the current position -$+ sum from j=1 to i-1 ( dx sub j , dy sub j )$. -At the moment, -GNU pic only uses this command to generate triangles and rectangles. +.BR groff (@MAN7EXT@) +for details of the +.I groff +language such as numerical units and escape sequences. +. .TP -\fBDP\fR $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\en -Like -.B Dp -but draw a solid rather than outlined polygon. +.BR groff_font (@MAN5EXT@) +for details on the device scaling parameters of the +.B DESC +file. +. .TP -\fBDt \fIn\fR\*(ic\en -Set the current line thickness to -.I n -machine units. -Traditionally Unix troff drivers use a line thickness proportional to the current -point size; drivers should continue to do this if no -.B Dt -command has been given, or if a -.B Dt -command has been given with a negative value of -.IR n . -A zero value of -.I n -selects the smallest available line thickness. -.LP -A difficulty arises in how the current position should be changed after -the execution of these commands. -This is not of great importance since the code generated by GNU pic -does not depend on this. -Given a drawing command of the form -.IP -\fB\eD\(fm\fIc\fR $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\(fm -.LP -where -.I c -is not one of -.BR c , -.BR e , -.BR l , -.B a -or -.BR ~ , -Unix troff will treat each of the $x sub i$ as a horizontal quantity, -and each of the $y sub i$ as a vertical quantity and will assume that -the width of the drawn object is $sum from i=1 to n x sub i$, -and that the height is $sum from i=1 to n y sub i$. -(The assumption about the height can be seen by examining the -.B st +.BR troff (@MAN1EXT@) +generates the device-independent intermediate output. +. +.TP +.BR roff (@MAN7EXT@) +for historical aspects and the general structure of roff systems. +. +.TP +.BR groff_diff (@MAN7EXT@) +The differences between the intermediate output in groff and classical +troff. +. +.P +.BR \%grodvi (@MAN1EXT@), +.BR \%grohtml (@MAN1EXT@), +.BR \%grolbp (@MAN1EXT@), +.BR \%grolj4 (@MAN1EXT@), +.BR \%grops (@MAN1EXT@), +.BR \%grotty (@MAN1EXT@) +.br +.RS +the groff postprocessor programs. +.RE +. +.P +For a treatment of all aspects of the groff system within a single +document, see the +.I groff info +.IR file . +. +It can be read within the integrated help systems, within +.BR emacs (1) +or from the shell prompt by +. +.RS +.ShellCommand info groff +.RE +. +.P +The +.I classical troff output language +is described in two AT&T Bell Labs CSTR documents available on-line at +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \ + "Bell Labs CSTR site" . +. +.TP +.I [CSTR #97] +.I A Typesetter-independent TROFF +by +.I Brian Kernighan +is the original and most concise documentation on the output language; +see +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz CSTR\~#97 . +. +.TP +.I [CSTR\~#54] +The 1992 revision of the +.I Nroff/\:Troff User's Manual +by +.I J.\& F.\& Osanna and -.B sb -registers after using such a -.B D -command in a \ew escape sequence.) -This rule also holds for all the original drawing commands -with the exception of -.BR De . -For the sake of compatibility GNU troff also follows this rule, -even though it produces an ugly result in the case of the -.BR Df , -.BR Dt , -and, to a lesser extent, -.B DE -commands. -Thus after executing a -.B D -command of the form -.IP -\fBD\fIc\fR $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\en -.LP -the current position should be increased by -$( sum from i=1 to n x sub i , sum from i=1 to n y sub i )$. -.LP -There is a continuation convention which permits the argument to the -.B x\ X -command to contain newlines: -when outputting the argument to the -.B x\ X -command, GNU troff -will follow each newline in the argument with a -.B + -character -(as usual, it will terminate the entire argument with a newline); -thus if the line after the line containing the -.B x\ X -command starts with -.BR + , -then the newline ending the line containing the -.B x\ X -command should be treated as part of the argument to the -.B x\ X -command, -the -.B + -should be ignored, -and the part of the line following the -.B + -should be treated like the part of the line following the -.B x\ X -command. -.SH "SEE ALSO" -.BR groff_font (@MAN5EXT@) +.I Brian Kernighan +isn't as concise as +.I [CSTR\~#97] +regarding the output language; +see +.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz CSTR\~#54 . +. +. +.\" -------------------------------------------------------------------- +.SH "AUTHORS" +.\" -------------------------------------------------------------------- +. +Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc. +.P +This document is distributed under the terms of the FDL (GNU Free +Documentation License) version 1.1 or later. +. +You should have received a copy of the FDL with this package; it is also +available on-line at the +.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . +. +.P +This document is part of +.IR groff , +the GNU roff distribution. +. +It is based on a former version \- published under the GPL \- that +described only parts of the +.I groff +extensions of the output language. +. +It has been rewritten 2002 by +.MTO bwarken@mayn.de "Bernd Warken" +and is maintained by +.MTO wl@gnu.org "Werner Lemberg" . +. +.\" -------------------------------------------------------------------- +.\" Emacs settings +.\" -------------------------------------------------------------------- .\" .\" Local Variables: .\" mode: nroff |