Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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: