/contrib/groff/man/groff_out.man
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 2106 lines · 2101 code · 5 blank · 0 comment · 0 complexity · c58990d4ca4e05ecd2b45f1eb962cb1a MD5 · raw file
- '\" e
- .\" The above line should force the use of eqn as a preprocessor
- .ig
- groff_out.5
- Last update: 2 Jul 2005
- This file is part of groff, the GNU roff type-setting system.
- Copyright (C) 1989, 2001, 2002, 2003, 2004, 2005
- Free Software Foundation, Inc.
- rewritten from scrach 2001 by Bernd Warken <bwarken@mayn.de>
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.1 or
- any later version published by the Free Software Foundation; with the
- Invariant Sections being this .ig-section and AUTHORS, with no
- Front-Cover Texts, and with no Back-Cover Texts.
- A copy of the Free Documentation License is included as a file called
- FDL in the main directory of the groff source package.
- ..
- .
- .\" --------------------------------------------------------------------
- .\" Setup
- .\" --------------------------------------------------------------------
- .
- .do nr groff_out_C \n[.C]
- .cp 0
- .
- .mso www.tmac
- .
- .if n \{\
- . mso tty-char.tmac
- . ftr CR R
- . ftr CI I
- . ftr CB B
- .\}
- .
- .if '\*[.T]'dvi' \
- . ftr CB CW
- .
- .if t \{\
- .EQ
- delim $$
- .EN
- .\}
- .
- .\" ----------------- Document configuration
- .
- .\" Number register to decide whether the commands `{' and `}' are used
- .\" 0: disable (actual default); 1: enable
- .nr @USE_ENV_STACK 0
- .
- .ig
- Unfortunately, old versions of groff used an illogical position change
- after some D\~commands (Dp, DP, Dt). If the number register
- @STUPID_DRAWING_POSITIONING is 1 (actual default) then change position
- after these commands, otherwise the position is not changed.
- ..
- .nr @STUPID_DRAWING_POSITIONING 1
- .
- .\" ----------------- Syntactical definitions
- .
- .\" comments when escapes are switched off
- .de c
- ..
- .\" Begin of macro definitions
- .eo
- .
- .de Text
- . nop \)\$*
- ..
- .c follow-up line for a .TP header
- .de TP+
- . br
- . ns
- . TP \$1
- ..
- .c a bulleted paragraph
- .de Topic
- . TP 2m
- . nop \[bu]
- ..
- .de ShellCommand
- . br
- . IR "shell>" "\h'1m'\f[CB]\$*\f[]\/"
- ..
- .ec
- .\" End of macro definitions
- .
- .c ----------------- Semantical definitions
- .
- .nr @maxcolor 65536
- .ds @backslash \[rs]\"
- .ds @linebreak \f[R]\[la]line_break\[ra]\f[]\"
- .
- .\" Begin of macro definitions
- .eo
- .
- .c format: .unit <letter> <punctuation>
- .de unit
- . BR \$@
- ..
- .c argument in italic with punctuation
- .de argument
- . if (\n[.$] == 0) \
- . return
- . IR \$@
- ..
- .c comma separated list of indexed variables
- .de list1..n
- . ds @arg1 \$1\"
- . nop \c
- . ie t \
- . nop $\*[@arg1] sub 1$, $\*[@arg1] sub 2$, .\|.\|., $\*[@arg1] sub n$ \c
- . el \{\
- . IR \*[@arg1]1 ,
- . IR \*[@arg1]2 ,
- . nop \&...,
- . I \*[@arg1]n
- . \}
- . rm @arg1
- ..
- .de offset
- . if (\n[.$] < 2) \
- . ab `.offset' needs at least 2 arguments
- . ds @arg1 \$1\"
- . ds @arg2 \$2\"
- . shift 2
- . nop (\f[I]\,\*[@arg1]\/\f[],\ \f[I]\,\*[@arg2]\/\f[])\$*
- . rm @arg1
- . rm @arg2
- ..
- .de indexed_offset
- . if (\n[.$] < 4) \
- . ab `.indexed_offset' needs at least 4 arguments
- . ds @arg1 \$1\"
- . ds @index1 \$2\"
- . ds @arg2 \$3\"
- . ds @index2 \$4\"
- . shift 4
- . ie t \{\
- . ie \B'\*[@index1]' \{\
- . nop ($\*[@arg1] sub roman \*[@index1]$,\ \c
- . \}
- . el \{\
- . nop ($\*[@arg1] sub \*[@index1]$,\ \c
- . \}
- . ie \B'\*[@index2]' \{\
- . nop $\*[@arg2] sub roman \*[@index2]$)\$* \c
- . \}
- . el \{\
- . nop $\*[@arg2] sub \*[@index2]$)\$* \c
- . \}
- . \}
- . el \{\
- . nop (\f[I]\*[@arg1]\*[@index1]\f[],\ \c
- . nop \f[I]\*[@arg2]\*[@index2]\f[])\$* \c
- . \}
- . rm @arg1
- . rm @arg2
- . rm @index1
- . rm @index2
- ..
- .c format: .command <name> "<arguments>" <punctuation>
- .de command
- . ds @arg1 \$1\"
- . ds @arg2 \$2\"
- . shift 2
- . IP "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
- . rm @arg1
- . rm @arg2
- ..
- .c format: .command+ <name> "<arguments>" <punctuation>
- .c continue previous .command heading
- .de command+
- . ds @arg1 \$1\"
- . ds @arg2 \$2\"
- . shift 2
- . TP+
- . Text "\f[B]\*[@arg1]\f[]\ \f[I]\,\*[@arg2]\/\f[]\$*"
- . rm @arg1
- . rm @arg2
- ..
- .c format: .D-command <subcommand> "<arguments>"
- .de D-command
- . ds @sub \$1\"
- . shift 1
- . IP "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\|\*[@linebreak]"
- . rm @sub
- ..
- .c format: .D-command+ <subcommand> "<arguments>"
- .c continue previous .D-command heading
- .de D-command+
- . ds @sub \$1\"
- . shift 1
- . TP+
- . Text "\f[B]D\*[@sub]\f[]\ \f[I]\,\$*\/\f[]\*[@linebreak]"
- . rm @sub
- ..
- .de Da-command
- . shift 1
- . ie t \
- . ds @args $h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$\"
- . el \
- . ds @args \f[I]h1\~v1 h2\~v2\f[]\"
- . IP "\f[B]Da\f[]\ \*[@args]\|\*[@linebreak]"
- . rm @args
- ..
- .c graphics command .D with a variable number of arguments
- .c format: .D-multiarg <subcommand>
- .de D-multiarg
- . ds @sub \$1\"
- . shift 1
- . ie t \{\
- . ds @args "$h sub 1$\~$v sub 1$ $h sub 2$\~$v sub 2$ .\|.\|. \"
- . as @args "$h sub n$\~$v sub n$\"
- . \}
- . el \
- . ds @args \f[I]h1\~v1 h2\~v2\f[] ... \f[I]\,hn\~vn\f[]\"
- . IP "\f[B]D\*[@sub]\f[]\ \*[@args]\|\*[@linebreak]"
- . rm @args
- . rm @sub
- ..
- .c format: .x-command <subname> "<arguments>"
- .de x-command
- . ds @sub \$1\"
- . shift 1
- . ds @args
- . if (\n[.$] > 0) \
- . ds @args \ \f[I]\,\$*\/\f[]\"
- . IP "\f[B]x\*[@sub]\f[]\*[@args]\f[]\|\*[@linebreak]"
- . rm @sub
- . rm @args
- ..
- .de xsub
- . RI "(" "\$1" " control command)"
- . br
- ..
- .ec
- .\" End of macro definitions
- .
- .
- .\" --------------------------------------------------------------------
- .\" Title
- .\" --------------------------------------------------------------------
- .
- .TH GROFF_OUT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
- .
- .SH NAME
- groff_out \- groff intermediate output format
- .
- .
- .\" --------------------------------------------------------------------
- .SH DESCRIPTION
- .\" --------------------------------------------------------------------
- .
- This manual page describes the
- .I intermediate output
- format of the GNU
- .BR roff (@MAN7EXT@)
- text processing system
- .BR groff (@MAN1EXT@).
- .
- This output is produced by a run of the GNU
- .BR @g@troff (@MAN1EXT@)
- program.
- .
- It contains already all device-specific information, but it is not yet
- fed into a device postprocessor program.
- .
- .
- .P
- As the GNU
- .I roff
- processor
- .BR groff (@MAN1EXT@)
- is a wrapper program around
- .B @g@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
- .I intermediate output
- is sent to standard output just like calling
- .B @g@troff
- manually.
- .
- .
- .P
- In this document, the term
- .I @g@troff output
- describes what is output by the GNU
- .B @g@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.
- .
- Both formats can be viewed directly with
- .BR \%gxditview (@MAN1EXT@).
- .
- .
- .P
- The main purpose of the
- .I 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
- .I intermediate output
- language is a kind of low-level assembler language by specifying all
- positions on the page for writing and drawing.
- .
- .
- .P
- The
- .RI pre- groff
- .I roff
- versions are denoted as
- .I classical
- .IR troff .
- The
- .I intermediate output
- produced by
- .B 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 @g@troff .
- .
- .
- .\" --------------------------------------------------------------------
- .SH "LANGUAGE CONCEPTS"
- .\" --------------------------------------------------------------------
- .
- During the run of
- .BR @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 "command" 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
- .B 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 to stack 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 ` 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
- .I 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
- .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 the section
- .BR "Device Control Commands" .
- .
- But 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 \[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
- .I intermediate
- .IR 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
- .I 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
- .I syntactical space
- or
- .I 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 [CSTR\~#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
- .I groff
- escape sequence
- .BR \*[@backslash]m .
- .
- No position changing.
- .
- These commands are a
- .I 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
- (an integer, normally non-negative) of the current font.
- .
- The print position is not changed.
- .
- If
- .B \-T\~html
- is used, negative values are emitted also to indicate an unbreakable space
- with given width.
- .
- For example,
- .B N\~-193
- represents an unbreakable space which has a width of 193u.
- .
- This command is a
- .I groff
- extension.
- .
- .
- .command n b\ a
- Inform the device about a line break, but no positioning is done by
- this command.
- .
- In
- .I classical
- .IR troff ,
- the integer arguments
- .argument b
- and\~\c
- .argument a
- informed about the space before and after the current line to
- make the
- .I intermediate output
- more human readable without performing any action.
- .
- In
- .IR 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 @g@troff ).
- .
- .I 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
- .I 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 and\~\c
- .argument n
- (an integer in
- basic units\~\c
- .unit u ).
- This command is a
- .I 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 [CSTR\~#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
- .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
- .B D\c
- \~command
- may not be followed by another command on the same line (apart from a
- comment), so each
- .B D\c
- \~command
- is terminated by a
- .I syntactical line
- .IR break .
- .
- .
- .P
- .B @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
- .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
- .B D\c
- \~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
- .I 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
- .I 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
- .I groff
- escape sequences
- .B \*[@backslash]D'F\ .\|.\|.'
- and
- .B \*[@backslash]M
- (with no other corresponding graphics commands).
- .
- No position changing.
- .
- This command is a
- .I 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
- .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
- .I 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
- .I 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
- .I 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
- .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,
- .B @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
- 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
- .B groff
- uses an internal piping mechanism.
- .
- The input file is not changed by this command.
- .
- This command is a
- .I 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 ).
- .
- .I 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
- .IR 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
- .IR prologue .
- .
- .
- .x-command S n
- .xsub Slant
- Set slant to\~\c
- .argument n
- degrees (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
- .I intermediate @g@troff
- .IR output .
- .
- .
- .x-command t
- .xsub trailer
- Generate trailer information, if any.
- .
- In
- .BR 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
- .IR prologue .
- .
- .
- .x-command u n
- .xsub underline
- Configure underlining of spaces.
- .
- If
- .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
- .B @g@nroff
- mode and is ignored otherwise.
- .
- This command is a
- .I 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
- .I 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
- .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 characters can become much larger than two
- decimal digits.
- .
- In
- .BR 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
- .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
- .BR FILES .
- .
- .
- .\" --------------------------------------------------------------------
- .SH "EXAMPLES"
- .\" --------------------------------------------------------------------
- .
- 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
- .B 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
- .I 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
- .I intermediate output
- language of the
- .I classical troff
- was first documented in
- .IR [CSTR\~#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
- .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 .
- .
- .
- .Topic
- The B-spline command
- .B D~
- is correctly handled by the
- .I 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
- .IR groff ,
- while
- .I 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
- .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) \{\
- .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
- 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
- .BR groff_diff (@MAN7EXT@).
- .
- .
- .\" --------------------------------------------------------------------
- .SH "FILES"
- .\" --------------------------------------------------------------------
- .
- .TP
- .BI @FONTDIR@/dev name /DESC
- Device description file for device
- .IR name .
- .
- .TP
- .IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cpp
- Defines the parser and postprocessor for the
- .I intermediate
- .IR 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
- .B 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
- .BR groff (@MAN1EXT@)
- option
- .B -Z
- and further readings on groff.
- .
- .
- .TP
- .BR groff (@MAN7EXT@)
- for details of the
- .I groff
- language such as numerical units and escape sequences.
- .
- .
- .TP
- .BR groff_font (@MAN5EXT@)
- for details on the device scaling parameters of the
- .B DESC
- file.
- .
- .
- .TP
- .BR @g@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.
- .
- .
- .TP
- .BR gxditview (@MAN1EXT@)
- Viewer for the
- .I intermediate
- .IR output .
- .
- .
- .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
- .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, 2003, 2004 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
- .I 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 \m[blue]Bernd Warken\m[] and is
- maintained by
- .MTO wl@gnu.org "Werner Lemberg" .
- .
- .cp \n[groff_out_C]
- .
- .\" --------------------------------------------------------------------
- .\" Emacs settings
- .\" --------------------------------------------------------------------
- .\"
- .\" Local Variables:
- .\" mode: nroff
- .\" End: