Use stock (FSF) version of this file.

4 files changed, 1902 insertions, 248 deletions

diff --git a/contrib/groff/man/groff_out.man b/contrib/groff/man/groff_out.man
index e743ddf..56dc571 100644
--- a/contrib/groff/man/groff_out.man
+++ b/contrib/groff/man/groff_out.man
@@ -1,254 +1,1890 @@
 '\" 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.
+Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc.
+rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de>
 
-	$FreeBSD$
+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.
+
+$FreeBSD$
+
+..
+.
+.\" --------------------------------------------------------------------
+.\" 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 \$@
 ..
-.\" This man page must be preprocessed with eqn.
-.ie \n(.g .ds ic \/
-.el .ds ic \^
+.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
diff --git a/contrib/groff/tmac/doc-common b/contrib/groff/tmac/doc-common
index 323d74f..4200bd3 100644
--- a/contrib/groff/tmac/doc-common
+++ b/contrib/groff/tmac/doc-common
@@ -152,7 +152,7 @@
 .nr Xr 10n
 .
 .
-.\" requests which must be processed after the closing delimiter of `Op'
+.\" macros which must be processed after the closing delimiter of `Op'
 .\" and friends
 .ds doc-after-Ao
 .ds doc-after-Bo
@@ -544,16 +544,16 @@
 .  doc-setup-page-layout
 .  if !\n[cR] \
 '    sp \n[doc-header-space]u
-.  nr doc-reg-dh \w'\*[doc-caption-font]\*[doc-header-string]\f[P]'
-.  nr doc-reg-dh1 \w'\*[doc-caption-font2]\*[doc-volume]\f[P]'
+.  nr doc-reg-dh \w'\*[doc-caption-font]\*[doc-header-string]\f[]'
+.  nr doc-reg-dh1 \w'\*[doc-caption-font2]\*[doc-volume]\f[]'
 .  if (\n[doc-reg-dh] + \n[doc-reg-dh1] + \n[doc-reg-dh] >= \n[.lt]) \{\
 .    while (\n[doc-reg-dh] + \n[doc-reg-dh1] + \n[doc-reg-dh] >= \n[.lt]) \{\
-.      substring doc-header-string 1 -1
-.      nr doc-reg-dh \w'\*[doc-caption-font]\*[doc-header-string]\|.\|.\|.\f[P]'
+.      substring doc-header-string 0 -2
+.      nr doc-reg-dh \w'\*[doc-caption-font]\*[doc-header-string]\|.\|.\|.\f[]'
 .    \}
 .    as doc-header-string "\|.\|.\|.
 .  \}
-.  tl \*[doc-caption-font]\*[doc-header-string]\f[P]\*[doc-caption-font2]\*[doc-volume]\f[P]\*[doc-caption-font]\*[doc-header-string]\f[P]
+.  tl \*[doc-caption-font]\*[doc-header-string]\f[]\*[doc-caption-font2]\*[doc-volume]\f[]\*[doc-caption-font]\*[doc-header-string]\f[]
 '  sp \n[doc-header-space]u
 .  ev
 ..
@@ -571,12 +571,12 @@
 '    sp \n[doc-footer-space]u
 .    ie \n[D] \{\
 .      ie o \
-.        tl %\*[doc-caption-font2]\*[doc-date-string]\f[P]\*[doc-caption-font]\*[doc-operating-system]\f[P]
+.        tl %\*[doc-caption-font2]\*[doc-date-string]\f[]\*[doc-caption-font]\*[doc-operating-system]\f[]
 .      el \
-.        tl \*[doc-caption-font]\*[doc-operating-system]\f[P]\*[doc-caption-font2]\*[doc-date-string]\f[P]%
+.        tl \*[doc-caption-font]\*[doc-operating-system]\f[]\*[doc-caption-font2]\*[doc-date-string]\f[]%
 .    \}
 .    el \
-.      tl \*[doc-caption-font]\*[doc-operating-system]\f[P]\*[doc-caption-font2]\*[doc-date-string]\f[P]%
+.      tl \*[doc-caption-font]\*[doc-operating-system]\f[]\*[doc-caption-font2]\*[doc-date-string]\f[]%
 '    bp
 .    ev
 .  \}
@@ -604,7 +604,7 @@
 .
 .  if \n[cR] \{\
 '    sp
-.    tl \*[doc-caption-font]\*[doc-operating-system]\f[P]\*[doc-caption-font2]\*[doc-date-string]\f[P]\*[doc-caption-font]\*[doc-operating-system]\f[P]
+.    tl \*[doc-caption-font]\*[doc-operating-system]\f[]\*[doc-caption-font2]\*[doc-date-string]\f[]\*[doc-caption-font]\*[doc-operating-system]\f[]
 .    \" suppress empty lines after the footer
 .    pl \n[nl]u
 .  \}
diff --git a/contrib/groff/tmac/doc-ditroff b/contrib/groff/tmac/doc-ditroff
index c4a9220..8f04bf8 100644
--- a/contrib/groff/tmac/doc-ditroff
+++ b/contrib/groff/tmac/doc-ditroff
@@ -101,12 +101,12 @@
 .ds doc-Va-font \f[I]\s[\n[.ps]u]
 .ds doc-Xr-font \f[C]\s[\n[.ps]u]
 .
-.ds doc-left-parenthesis \f[R]\|(\|\f[P]\s[\n[.ps]u]
-.ds doc-right-parenthesis \f[R]\|)\|\f[P]\s[\n[.ps]u]
-.ds lp \f[R](\f[P]\s[\n[.ps]u]
-.ds rp \f[R])\f[P]\s[\n[.ps]u]
-.ds doc-left-bracket \f[R]\^[\^\f[P]\s[\n[.ps]u]
-.ds doc-right-bracket \f[R]\^]\f[P]\s[\n[.ps]u]
+.ds doc-left-parenthesis \f[R]\|(\|\f[]\s[\n[.ps]u]
+.ds doc-right-parenthesis \f[R]\|)\|\f[]\s[\n[.ps]u]
+.ds lp \f[R](\f[]\s[\n[.ps]u]
+.ds rp \f[R])\f[]\s[\n[.ps]u]
+.ds doc-left-bracket \f[R]\^[\^\f[]\s[\n[.ps]u]
+.ds doc-right-bracket \f[R]\^]\f[]\s[\n[.ps]u]
 .
 .tr *\[**]
 .
@@ -150,8 +150,16 @@
 .  nr doc-header-space .5i
 .  nr doc-footer-space .5i
 .
-.  ll 6.5i
-.  lt 6.5i
+.  ie r LL \
+.    ll \n[LL]u
+.  el \
+.    ll 6.5i
+.
+.  ie r LT \
+.    lt \n[LT]u
+.  el \
+.    lt 6.5i
+.
 .  po 1i
 .
 .  nr doc-display-vertical .5v
@@ -178,8 +186,9 @@
 .ds Gt >
 .ds Pm \[+-]
 .ds If \[if]
-.ds Na \f[I]NaN\f[P]
-.ds Ba \f[R]|\f[P]
+.ds Na \f[I]NaN\f[]
+.ds Ba \f[R]|\f[]
+.ds Am &
 .
 .nr gX 0
 .
diff --git a/contrib/groff/tmac/doc-nroff b/contrib/groff/tmac/doc-nroff
index 8416ad6..a0f1856 100644
--- a/contrib/groff/tmac/doc-nroff
+++ b/contrib/groff/tmac/doc-nroff
@@ -79,12 +79,12 @@
 .ds doc-Va-font \f[I]
 .ds doc-Xr-font \f[R]
 .
-.ds doc-left-parenthesis \f[R](\f[P]
-.ds doc-right-parenthesis \f[R])\f[P]
-.ds lp \f[R](\f[P]
-.ds rp \f[R])\f[P]
-.ds doc-left-bracket \f[R][\f[P]
-.ds doc-right-bracket \f[R]]\f[P]
+.ds doc-left-parenthesis \f[R](\f[]
+.ds doc-right-parenthesis \f[R])\f[]
+.ds lp \f[R](\f[]
+.ds rp \f[R])\f[]
+.ds doc-left-bracket \f[R][\f[]
+.ds doc-right-bracket \f[R]]\f[]
 .
 .\" miscellaneous
 .nr doc-subheader-indent .5i
@@ -129,8 +129,16 @@
 .    nr doc-header-space .5i
 .  nr doc-footer-space .5i
 .
-.  ll 78n
-.  lt 78n
+.  ie r LL \
+.    ll \n[LL]u
+.  el \
+.    ll 78n
+.
+.  ie r LT \
+.    lt \n[LT]u
+.  el \
+.    lt 78n
+.
 .  po 0i
 .
 .  nr doc-display-vertical 1v
@@ -156,8 +164,9 @@
 .ds Lt <
 .ds Gt >
 .ds Pm \[+-]
-.ds Na \f[I]NaN\f[P]
-.ds Ba \f[R]|\f[P]
+.ds Na \f[I]NaN\f[]
+.ds Ba \f[R]|\f[]
+.ds Am &
 .
 .\" Unicode TTYs have all glyph forms; for other TTY character sets we need
 .\" character representations which are different from GNU troff's standard