diff options
Diffstat (limited to 'man/groff_out.5.man')
| -rw-r--r-- | man/groff_out.5.man | 1963 |
1 files changed, 1963 insertions, 0 deletions
diff --git a/man/groff_out.5.man b/man/groff_out.5.man new file mode 100644 index 0000000..9c1534e --- /dev/null +++ b/man/groff_out.5.man @@ -0,0 +1,1963 @@ +.TH groff_out @MAN5EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +groff_out \- GNU +.I roff +intermediate output format +. +. +.\" XXX: This page needs review and editing. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2023 Free Software Foundation, Inc. +.\" +.\" This file is part of groff, the GNU roff type-setting system. +.\" +.\" Permission is granted to copy, distribute and/or modify this +.\" document under the terms of the GNU Free Documentation License, +.\" Version 1.3 or any later version published by the Free Software +.\" Foundation; with no Invariant Sections, 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. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_out_5_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.\" Setup +.\" ==================================================================== +. +.\" ================= Document configuration +. +.\" Number register to decide whether the commands '{' and '}' are used +.\" 0: disable (current 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 register +@STUPID_DRAWING_POSITIONING is 1 (current default) then change position +after these commands, otherwise the position is not changed. +.. +.nr @STUPID_DRAWING_POSITIONING 1 +. +.\" ================= Semantical definitions +. +.nr @maxcolor 65536 +.ds @backslash \[rs]\" +.ds @linebreak \fR\[la]line-break\[ra]\fP\" +. +.\" Begin of macro definitions +. +.de offset +.RI ( \,\\$1\/ ,\ \,\\$2\/ )\\$3 +.. +.de indexed_offset +.offset \fI\\$1\/\fP\d\s-3\\$2\s+3\u\x'\n[.v]/4' \fI\\$3\/\fP\ +\d\s-3\\$4\s+3\u\x'\n[.v]/4' \\$5\x'\n[.v]/4' +.. +.\" format: .command <name> "<arguments>" <punctuation> +.de command +\fB\\$1\fP\ \fI\,\\$2\/\fP\\$3 +.. +.\" format: .D-command <subcommand> "<arguments>" +.de D-command +\fBD\\$1\fP\ \fI\,\\$2\/\fP\|\*[@linebreak] +.. +. +.\" We set these as troff micromotions rather than eqn because \d and \u +.\" can be lifted to XML subscript/superscript tags. Don't change +.\" these to a parameterized string, man2html won't handle that. +.ds hv1 \fIh\d\s-3\&1\s+3\u\~v\d\s-3\&1\s+3\u\fP\x'\n[.v]/4' +.ds hv2 \fIh\d\s-3\&2\s+3\u\~v\d\s-3\&2\s+3\u\fP\x'\n[.v]/4' +.ds hvn \fIh\d\s-3\&n\s+3\u\~v\d\s-3\&n\s+3\u\fP\x'\n[.v]/4' +. +.de Da-command +\fBDa\fP\ \*[hv1] \*[hv2]\|\*[@linebreak] +.. +.\" graphics command .D with a variable number of arguments +.\" format: .D-multiarg <subcommand> +.de D-multiarg +\fBD\\$1\fP\ \*[hv1] \*[hv2] \&.\|.\|.\& \*[hvn]\|\*[@linebreak] +.. +.\" format: .x-command <subname> "<arguments>" +.de x-command +\fBx\\$1\fP\ \fI\\$2\fP\|\*[@linebreak] +.. +.de xsub +.RI "(" "\\$1" " control command)" +.br +.. +.\" End of macro definitions +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The fundamental operation of the +.MR @g@troff @MAN1EXT@ +formatter is the translation of the +.MR groff @MAN7EXT@ +input language into a series of instructions concerned primarily with +placing glyphs or geometric objects at specific positions on a +rectangular page. +. +In the following discussion, +the term +.I command +refers to this intermediate output language, +never to the +.MR groff @MAN7EXT@ +language intended for use by document authors. +. +Intermediate output commands comprise several categories: +glyph output; +font, +color, +and text size selection; +motion of the printing position; +page advancement; +drawing of geometric primitives; +and device control commands, +a catch-all for other operations. +. +The last includes directives to start and stop output, +identify the intended output device, +and embed URL hyperlinks in supported output formats. +. +. +.P +Because the front-end command +.MR groff @MAN1EXT@ +is a wrapper that normally runs the +.I @g@troff +formatter to generate intermediate output +and an output driver (\[lq]postprocessor\[rq]) to consume it, +users normally do not encounter this language. +. +The +.I groff +program's +.B \-Z +option inhibits postprocessing such that this intermediate output is +sent to the standard output stream as when +.I @g@troff +is run manually. +. +. +.P +.IR groff 's +intermediate output facilitates the development of output drivers and +other postprocessors by offering a common programming interface. +. +It is an extension of the page description language developed by Brian +Kernighan for AT&T device-independent +.I troff \" AT&T +circa 1980. +. +Where a distinction is necessary, +we will say +.RI \[lq] @g@troff +output\[rq] to describe the output of GNU +.IR troff , \" GNU +and \[lq]intermediate output\[rq] to denote the language accepted by +the parser implemented in +.IR groff 's +internal C++ library used by most of its output drivers. +.\" XXX GBR leaves off here. +. +. +.\" ==================================================================== +.SH "Language concepts" +.\" ==================================================================== +. +During the run of +.IR @g@troff , +the +.I 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 +.I intermediate output +format can be quite small. +. +Its only elements are commands with or without arguments. +. +In this document, the term \[lq]command\[rq] always refers to the +.I intermediate output +language, never to the +.I 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 +.I syntactical +.IR 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 +.I syntactical +.IR 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 +.I syntactical line break +is defined to consist of optional +.I 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 stacking of such commands on +the same line, but fortunately, in +.I groff intermediate +.IR 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 \[oq] x\ X \[cq] +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 split by a line break. +. +.P +Lines containing only spaces and/or a comment are treated as empty and +ignored. +. +. +.\" ==================================================================== +.SS "Argument units" +.\" ==================================================================== +. +Some commands accept integer arguments that represent measurements, +but the scaling units of the formatter's language are never used. +. +Most commands assume a scaling unit +.RB of\~\[lq] u \[rq] +(basic units), +and others +.RB use\~\[lq] z \[rq] +(scaled points); +. +These are defined by the parameters specified in the device's +.I DESC +file; +see +.MR groff_font @MAN5EXT@ +and, +for more on scaling units, +.MR groff @MAN7EXT@ +and +.IR "Groff: The GNU Implementation of troff" , +the +.I groff +Texinfo manual. +. +Color-related commands use dimensionless integers. +. +. +.P +Note that single characters can have the eighth bit set, as can the +names of fonts and special characters (this is, glyphs). +. +The names of glyphs and fonts can be of arbitrary length. +. +A glyph 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 +.I intermediate output +document consists of two parts, the +.I prologue +and the +.IR 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 +.B x\ res +.I n\ h\ v +.br +.B x init +.RE +.P +with the arguments set as outlined in subsection \[lq]Device Control +Commands\[rq] below. +. +However, the parser for the +.I 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 +.IR prologue . +. +Processing is terminated as soon as the first +.B x\ stop +command is encountered; the last line of any +.I groff intermediate output +always contains such a command. +. +. +.P +Semantically, the +.I 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 +.I intermediate output +commands, the classical commands as well as the +.I groff +extensions. +. +. +.\" ==================================================================== +.SS "Comment command" +.\" ==================================================================== +. +.TP +.BI # anything\c +\[la]line-break\[ra] +A comment. +. +Ignore any characters from the +.BR # \~character +up to the next newline. +. +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 +.I syntactical space +is necessary only when two integer arguments would clash or if the +preceding argument ends with a string argument. +. +. +.if \n[@USE_ENV_STACK]=1 \{\ +.TP +.command { +Open a new environment by copying the current device configuration data +to the environment stack. +. +The current environment is setup by the device specification and +manipulated by the setting commands. +. +. +.TP +.command } +Close the current environment +(opened by a preceding +.BR { \~command) +and restore the previous environment from the environment +stack as the current device configuration data. +. +.\} \" endif @USE_ENV_STACK +. +. +.TP +.command C id \[la]white-space\[ra] +Typeset the glyph of the special character +.IR id . +. +Trailing syntactical space is necessary to allow special character names +of arbitrary length. +. +The drawing position is not advanced. +.\" XXX: Why does it matter that we read its size if we don't advance +.\" the drawing position? +.\" its size is read from the font description file. +. +. +.TP +.command c c +Typeset the glyph of the ordinary character +.RI character\~ c . +. +The drawing position is not advanced. +.\" XXX: Why does it matter that we read its size if we don't advance +.\" the drawing position? +.\" its size is read from the font description file. +. +. +.TP +.command f n +Select the font mounted at +.RI position\~ n . +. +.IR n\~ cannot +be negative. +. +. +.TP +.command H n +Horizontally move the drawing position to +.IR n\~ basic +units from the left edge of the page. +. +.IR n\~ cannot +be negative. +. +. +.TP +.command h n +Move the drawing position right +.I n +basic units. +. +AT&T +.I troff \" AT&T +allowed negative +.I n; +GNU +.I troff \" GNU +does not produce such values, +but +.IR groff 's +output driver library handles them. +. +. +.TP +.command m "scheme \f[R][\f[]component\f[R] .\|.\|.]" +Select the stroke color using the +.IR component s +in the color space +.IR scheme . +. +Each +.I component +is an integer between 0 and \n[@maxcolor]. +. +The quantity of components and their meanings vary with each +.IR scheme . +. +This command is a +.I groff +extension. +. +. +.RS +.TP +.command mc "cyan magenta yellow" +Use the CMY color scheme with components +cyan, +magenta, +and yellow. +. +. +.TP +.command md +Use the default color +(no components; +black in most cases). +. +. +.TP +.command mg gray +Use a grayscale color scheme with a component ranging +between 0 (black) and \n[@maxcolor] (white). +. +. +.TP +.command mk "cyan magenta yellow black" +Use the CMYK color scheme with components +cyan, +magenta, +yellow, +and black. +. +. +.TP +.command mr "red green blue" +Use the RGB color scheme with components +red, +green, +and blue. +.RE +. +. +.TP +.command N n +Typeset the glyph with +.RI index\~ n +in the current font. +. +.IR n\~ is +normally a non-negative integer. +. +The drawing position is not advanced. +. +The +.B html +and +.B xhtml +devices use this command with +.RI negative\~ n +to produce unbreakable space; +the absolute value of +.I n +is taken and interpreted in basic units. +. +. +.TP +.command n b\~a +Indicate a break. +. +No action is performed; +the command is present to make the output more easily parsed. +. +The integers +.I b +.RI and\~ a +describe the vertical space amounts before and after the break, +respectively. +. +GNU +.I troff \" GNU +issues this command but +.IR groff 's +output driver library ignores it. +. +See +.B v +and +.BR V . +. +. +.TP +.command p n +Begin a new page, +setting its number +.RI to\~ n . +. +Each page is independent, +even from those using the same number. +. +The vertical drawing position is set to\~0. +. +All positioning, +writing, +and drawing commands are interpreted in the context of a page, +so a +.BR p \~command +must precede them. +. +. +.TP +.command s n +Set type size to +.I n +scaled points +.RB (unit\~ z +in GNU +.IR troff ). \" GNU +. +AT&T +.I troff \" AT&T +used unscaled points +.RB ( p ) +instead; +see section \[lq]Compatibility\[rq] below. +. +. +.TP +.command t xyz\f[R]\|.\|.\|.\& \f[R]\[la]white-space\[ra] +.TQ +.command t "xyz\f[R]\|.\|.\|.\&\f[] dummy-arg" \[la]white-space\[ra] +Typeset word +.IR xyz ; +that is, +set a sequence of ordinary glyphs named +.IR x , +.IR y , +.IR z , +\&.\|.\|.\|, +terminated by a space or newline; +an optional second integer argument is ignored +(this allows the formatter to generate an even number of arguments). +.\" XXX: Why? +. +Each glyph is set at the current drawing position, +and the position is then advanced horizontally by the glyph's width. +. +A glyph's width is read from its metrics in the font description file, +scaled to the current type size, +and rounded to a multiple of the horizontal motion quantum. +. +Use the +.B C +command to emplace glyphs of special characters. +. +The +.BR t \~command +is a +.I groff +extension and is output only for devices whose +.I DESC +file contains the +.B tcommand +directive; +see +.MR groff_font @MAN5EXT@ . +. +. +.TP +.command u "n xyz"\f[R]\|.\|.\|.\& \f[R]\[la]white-space\[ra] +.TQ +.command u "xyz\f[R]\|.\|.\|.\&\f[] dummy-arg" \[la]white-space\[ra] +Typeset word +.I xyz +with track kerning. +. +As +.BR t , +but after placing each glyph, +the drawing position is further advanced horizontally +.RI by\~ n +basic units. +. +The +.BR u \~command +is a +.I groff +extension and is output only for devices whose +.I DESC +file contains the +.B tcommand +directive; +see +.MR groff_font @MAN5EXT@ . +. +. +.TP +.command V n +Vertically move the drawing position to +.IR n\~ basic +units from the top edge of the page. +. +.IR n\~ cannot +be negative. +. +. +.TP +.command v n +Move the drawing position down +.I n +basic units. +. +AT&T +.I troff \" AT&T +allowed negative +.I n; +GNU +.I troff \" GNU +does not produce such values, +but +.IR groff 's +output driver library handles them. +. +. +.TP +.command w +Indicate an inter-word space. +. +No action is performed; +the command is present to make the output more easily parsed. +. +Only adjustable, +breakable inter-word spaces are thus described; +those resulting from +.B \[rs]\[ti] +or horizontal motion escape sequences are not. +. +GNU +.I troff \" GNU +issues this command but +.IR groff 's +output driver library ignores it. +. +See +.B h +and +.BR H . +. +. +.\" ==================================================================== +.SS "Graphics commands" +.\" ==================================================================== +. +Each graphics or drawing command in the +.I 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 +.I syntactical line +.IR break . +. +. +.P +.I @g@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 +.BR u . +. +The +.I h +arguments +stand for horizontal distances where positive means right, negative +left. +. +The +.I v +arguments +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 +.MR groff @MAN7EXT@ . +. +. +.P +Unknown +.BR 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 subsection \[lq]Separation\[rq] above. +. +. +.TP +.D-multiarg \[ti] +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. +. +. +.TP +.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. +. +. +.TP +.D-command C d +.TQ +.D-command C "d dummy-arg" +Draw a solid circle using the current fill color with diameter\~\c +.I d +(integer in basic units\~\c +.BR 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 +.I groff +extension. +. +. +.TP +.D-command c d +Draw circle line with diameter\~\c +.I d +(integer in basic units\~\c +.BR u ) +with leftmost point at the current position; then move the current +position to the rightmost point of the circle. +. +. +.TP +.D-command E "h v" +Draw a solid ellipse in the current fill color with a horizontal +diameter of\~\c +.I h +and a vertical diameter of\~\c +.I v +(both integers in basic units\~\c +.BR u ) +with the leftmost point at the current position; then move to the +rightmost point of the ellipse. +. +This command is a +.I groff +extension. +. +. +.TP +.D-command e "h v" +Draw an outlined ellipse with a horizontal diameter of\~\c +.I h +and a vertical diameter of\~\c +.I v +(both integers in basic units\~\c +.BR u ) +with the leftmost point at current position; then move to the +rightmost point of the ellipse. +. +. +.TP +.D-command F "color-scheme \fR[\fPcomponent\fR .\|.\|.]\fP" +Set fill color for solid drawing objects using different color +schemes; the analogous command for setting the color of text, line +graphics, and the outline of graphic objects is +.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 +.I groff +escape sequences +.BR \*[@backslash]D\[aq]F\ .\|.\|. ' +and +.B \*[@backslash]M +(with no other corresponding graphics commands). +. +This command is a +.I groff +extension. +. +. +.RS +. +.TP +.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. +. +. +.TP +.D-command Fd +Set fill color for solid drawing objects to the default fill color value +(black in most cases). +. +No component arguments. +. +. +.TP +.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). +. +. +.TP +.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. +. +.TP +.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 +. +. +.TP +.D-command f n +The argument +.I n +must be an integer in the range \-32767 to 32767. +. +.RS +.TP +.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 +. +.RS +.IP +.EX +mg 0 0 \n[@maxcolor] +Df \-1 +.EE +.RE +. +.IP +sets all colors to blue. +. +.P +This command is a +.I groff +extension. +. +.RE +. +. +.TP +.D-command l "h v" +Draw line from current position to offset +.offset h v +(integers in basic units\~\c +.BR u ); +then set current position to the end of the drawn line. +. +. +.TP +.D-multiarg p +Draw a polygon line from current position to offset +.indexed_offset h 1 v 1 , +from there to offset +.indexed_offset h 2 v 2 , +etc., up to offset +.indexed_offset h n v n , +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 current 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 +.I groff +extension. +. +. +.TP +.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. +. +.if \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +The position is changed in the same way as with +.BR Dp . +.\} +. +This command is a +.I groff +extension. +. +. +.TP +.D-command t n +Set the current line thickness +.RI to\~ n +(an integer in basic +.RB units\~ u ) +if +.IR n \|>\|0; +if +.IR n \|=\|0 +select the smallest available line thickness; +otherwise, +the line thickness is made proportional to the type size, +which is the default. +. +.if \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +For historical reasons, +the horizontal position is changed by adding the argument to the current +horizontal position, +while the vertical position is not changed. +. +Although this doesn't make sense, +it is kept for compatibility. +.\} +. +This command is a +.I 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 +.IR groff ) +and a subcommand letter or word; each argument (if any) must be +preceded by a +.I syntactical +.IR 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 @g@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 +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 subsection \[lq]Separation\[rq] above. +. +.TP +.x-command F name +.xsub Filename +Use +.I name +as the intended name for the current file in error reports. +. +This is useful for remembering the original file name when +.I groff +uses an internal piping mechanism. +. +The input file is not changed by this command. +. +This command is a +.I groff +extension. +. +. +.TP +.x-command f "n\ s" +.xsub font +Mount font position\~\c +.I n +(a non-negative integer) with font named\~\c +.I s +(a text word); +see +.MR groff_font @MAN5EXT@ . +. +. +.TP +.x-command H n +.xsub Height +Set character height to\~\c +.I n +(a positive integer in scaled points\~\c +.BR z ). +. +.I Classical troff +used the unit points (\c +.BR p ) +instead; +see section \[lq]Compatibility\[rq] below. +. +. +.TP +.x-command i +.xsub init +Initialize device. +. +This is the third command of the +.IR prologue . +. +. +.TP +.x-command p +.xsub pause +Parsed but ignored. +. +The classical documentation reads +.I pause device, can be +.IR restarted . +. +. +.TP +.x-command r "n\ h\ v" +.xsub resolution +Resolution is\~\c +.IR n , +while +.I h +is the minimal horizontal motion, and +.I v +the minimal vertical motion possible with this device; all arguments +are positive integers in basic units\~\c +.B u +per inch. +. +This is the second command of the +.IR prologue . +. +. +.TP +.x-command S n +.xsub Slant +Set slant to\~\c +.I n +degrees (an integer in basic units\~\c +.BR u ). +. +. +.TP +.x-command s +.xsub stop +Terminates the processing of the current file; issued as the last +command of any +.I intermediate @g@troff +.IR output . +. +. +.TP +.x-command t +.xsub trailer +Generate trailer information, if any. +. +In +.BR groff , +this is currently ignored. +. +. +.TP +.x-command T xxx +.xsub Typesetter +. +Set the name of the output driver to +.IR xxx , +a sequence of non-whitespace characters terminated by whitespace. +. +The possible names correspond to those of +.IR groff 's +.B \-T +option. +. +This is the first command of the prologue. +. +. +.TP +.x-command u n +.xsub underline +Configure underlining of spaces. +. +If +.I n +is\~1, start underlining of spaces; +if +.I n +is\~0, stop underlining of spaces. +. +This is needed for the +.B cu +request in +.B @g@nroff +mode and is ignored otherwise. +. +This command is a +.I groff +extension. +. +. +.TP +.x-command X anything +.xsub X-escape +Send string +.I 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 +.I groff +extension. +. +. +.\" ==================================================================== +.SS "Obsolete command" +.\" ==================================================================== +. +In +.I classical troff +output, emitting a single glyph was mostly done by a very +strange command that combined a horizontal move and the printing of a +glyph. +. +It didn't have a command code, but is represented by a 3-character +argument consisting of exactly 2\~digits and a character. +. +.TP +.I ddc +Move right +.I dd +(exactly two decimal digits) basic units\~\c +.BR u , +then print glyph with single-letter name\~\c +.IR c . +. +. +.RS +.P +In +.IR groff , +arbitrary +.I 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 glyphs can become much larger than two +decimal digits. +. +In +.IR groff , +it is used only for output to the +.BR X75 , +.BR X75\-12 , +.BR X100 , +and +.B X100\-12 +devices. +. +For others, +the commands +.B t +.RB and\~ u +provide greater functionality and superior troubleshooting capacity. +. +. +.\" ==================================================================== +.SH Postprocessing +.\" ==================================================================== +. +The +.I roff +postprocessors are programs that have the task to translate the +.I 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 +.I 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 \[lq]Files\[rq] below. +. +. +.\" ==================================================================== +.SH Example +.\" ==================================================================== +. +This section presents the +.I intermediate output +generated from the same input for three different devices. +. +The input is the sentence +.I hell world +fed into +.I groff +on the command line. +. +. +.IP \[bu] 2m +High-resolution device +.I ps +. +. +.RS +.P +.EX +.RB "shell>\~" "echo \[dq]hell world\[dq] | groff \-Z \-T ps" +.EE +. +. +.P +.EX +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 +.EE +.RE +. +. +.P +This output can be fed into the postprocessor +.MR grops @MAN1EXT@ +to get its representation as a PostScript file, or +.MR gropdf @MAN1EXT@ +to output directly to PDF. +. +. +.IP \[bu] 2m +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 +.EX +\fBshell>\fP "hell world" | groff \-Z \-T latin1 +.EE +. +. +.P +.EX +.I # prologue +x T latin1 +x res 240 24 40 +x init +.I # begin a new page +p1 +.I # font setup +x font 1 R +f1 +s10 +.I # initial positioning on the page +V40 +H0 +.I # write text \[aq]hell\[aq] +thell +.I # inform about a space, and do it by a horizontal jump +wh24 +.I # write text \[aq]world\[aq] +tworld +.I # announce line break, but do nothing because ... +n40 0 +.I # ... the end of the document has been reached +x trailer +V2640 +x stop +.EE +.RE +. +. +.P +This output can be fed into the postprocessor +.MR grotty @MAN1EXT@ +to get a formatted text document. +. +. +.IP \[bu] 2m +Classical style output +. +. +.RS +.P +As a computer monitor has a very low resolution compared to modern +printers the +.I intermediate output +for the X\~devices can use the jump-and-write command with its 2-digit +displacements. +. +. +.P +.EX +\fBshell>\fP "hell world" | groff \-Z \-T X100 +.EE +. +. +.P +.EX +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 +ch07e07l03lw06w11o07r05l03dh7 +n16 0 +x trailer +V1100 +x stop +.EE +.RE +. +. +.P +This output can be fed into the postprocessor +.MR xditview 1x +or +.MR 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 +.I intermediate output +language of the +.I classical troff +was first documented in +[CSTR\~#97]. +. +The +.I groff intermediate output +format is compatible with this specification except for the following +features. +. +. +.IP \[bu] 2m +The classical quasi device independence is not yet implemented. +. +. +.IP \[bu] 2m +The old hardware was very different from what we use today. +. +So the +.I groff +devices are also fundamentally different from the ones in +.I classical +.IR troff . +. +For example, the classical PostScript device was called +.I post +and had a resolution of 720 units per inch, +while +.IR 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 +.IR groff . +. +. +.IP \[bu] 2m +The B-spline command +.B D\[ti] +is correctly handled by the +.I intermediate output +parser, but the drawing routines aren't implemented in some of the +postprocessor programs. +. +. +.IP \[bu] 2m +The argument of the commands +.B s +and +.B x H +has the implicit unit scaled point\~\c +.B z +in +.IR groff , +while +.I classical troff +had point (\c +.BR 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 +.I groff +text devices. +. +The few +.I 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 \{\ +.IP \[bu] 2m +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 \{\ +.IP \[bu] 2m +Temporarily, there existed some confusion on the positioning after the +.B D +commands that are +.I groff +extensions. +. +This has been clarified by establishing the classical rule for all +groff drawing commands: +. +. +.RS +.P +.ft I +The position after a graphic object has been drawn is at its end; +for circles and ellipses, the "end" is at the right side. +.ft +.RE +. +. +.P +From this, the positionings specified for the drawing commands above +follow quite naturally. +.\} \" @STUPID_DRAWING_POSITIONING +. +.P +The differences between +.I groff +and +.I classical troff +are documented in +.MR groff_diff @MAN7EXT@ . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.IR @FONTDIR@/\:\%dev name /\:DESC +describes the output device +.IR name . +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +James Clark wrote an early version of this document, +which described only the differences between AT&T +device-independent +.IR troff 's +output format and that of GNU +.IR roff . +. +The present version was completely rewritten in 2001 by +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.P +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.P +\[lq]Troff User's Manual\[rq] +by Joseph F.\& Ossanna, +1976 +(revised by Brian W.\& Kernighan, +1992), +AT&T Bell Laboratories Computing Science Technical Report No.\& 54, +widely called simply \[lq]CSTR\~#54\[rq], +documents the language, +device and font description file formats, +and device-independent output format +referred to collectively in +.I groff +documentation as +.RI \[lq]AT&T\~ troff \[rq]. +. +. +.P +\[lq]A Typesetter-independent TROFF\[rq] +by Brian W.\& Kernighan, +1982, +AT&T Bell Laboratories Computing Science Technical Report No.\& 97, +provides additional insights into the +device and font description file formats +and device-independent output format. +. +. +.TP +.MR groff @MAN1EXT@ +documents the +.B \-Z +option and contains pointers to further +.I groff +documentation. +. +. +.TP +.MR groff @MAN7EXT@ +describes the +.I groff +language, +including its escape sequences and system of units. +. +. +.TP +.MR groff_font @MAN5EXT@ +details the device scaling parameters of device +.I DESC +files. +. +. +.TP +.MR @g@troff @MAN1EXT@ +generates the device-independent intermediate output documented here. +. +. +.TP +.MR roff @MAN7EXT@ +presents historical aspects and the general structure of +.I roff +systems. +. +. +.TP +.MR groff_diff @MAN7EXT@ +enumerates differences between the intermediate output produced by AT&T +.I troff \" AT&T +and that of +.IR groff . +. +. +.TP +.MR gxditview @MAN1EXT@ +is a viewer for intermediate output. +. +. +.TP +.UR https://\:github.com/\:Alhadis/\:Roff\:.js/ +.I Roff.js +.UE +is a viewer for intermediate output written in JavaScript. +. +. +.P +.MR grodvi @MAN1EXT@ , +.MR grohtml @MAN1EXT@ , +.MR grolbp @MAN1EXT@ , +.MR grolj4 @MAN1EXT@ , +.MR gropdf @MAN1EXT@ , +.MR grops @MAN1EXT@ , +and +.MR grotty @MAN1EXT@ +are +.I groff +postprocessors. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_out_5_man_C] +.do rr *groff_groff_out_5_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |