The output format of groff is modeled after that used by AT&T
troff once it adopted a device-independent approach in the early
1980s. Only the differences are documented here.
Units
The argument to the s command is in scaled points (in units of
points/n, where n is the argument to the sizescale command in the
DESC file). The argument to the x Height command is also in
scaled points.
Text commands
Nn Print glyph with index n (a non-negative integer) of the
current font.
If the tcommand line is present in the DESC file, GNU troff uses
the following two commands.
txxx xxx is any sequence of characters terminated by a space or
a newline (to be more precise, it is a sequence of glyphs
which are accessed with the corresponding characters); the
first character should be printed at the current position,
the current horizontal position should be increased by the
width of the first character, and so on for each
character. The width of the glyph 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.
un xxx This is same as the t command except that after printing
each character, the current horizontal position is
increased by the sum of the width of that character and n.
Note that single characters can have the eighth bit set, as can
the names of fonts and special characters.
The names of glyphs and fonts can be of arbitrary length; drivers
should not assume that they are only two characters long.
When a glyph is to be printed, that glyph is always in the
current font. Unlike device-independent troff, it is not
necessary for drivers to search special fonts to find a glyph.
For color support, some new commands have been added:
mc cyan magenta yellow
md
mg gray
mk cyan magenta yellow black
mr red green blue
Set the color components of the current drawing color,
using various color schemes. md resets the drawing color
to the default value. The arguments are integers in the
range 0 to 65536.
The x device control command has been extended.
x u n If n is 1, start underlining of spaces. If n is 0, stop
underlining of spaces. This is needed for the cu request
in nroff mode and is ignored otherwise.
Drawing commands
The D drawing command has been extended. These extensions are
not used by GNU pic if the -n option is given.
Df n\n Set the shade of gray to be used for filling solid objects
to n; 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 is 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 is black, but some drivers may
provide a way of changing this.
The corresponding \D'f...' command shouldn't be used since
its argument is always rounded to an integer multiple of
the horizontal resolution which can lead to surprising
results.
DC d\n Draw a solid circle with a diameter of d with the leftmost
point at the current position.
DE dx dy\n
Draw a solid ellipse with a horizontal diameter of dx and
a vertical diameter of dy with the leftmost point at the
current position.
Dp dx1 dy1 dx2 dy2 ... dxn dyn\n
Draw a polygon with, for i=1,...,n+1, the i-th vertex at
the current position +ij−=Σ11(dxj,dyj). At the moment, GNU
pic only uses this command to generate triangles and
rectangles.
DP dx1 dy1 dx2 dy2 ... dxn dyn\n
Like Dp but draw a solid rather than outlined polygon.
Dt n\n Set the current line thickness to n machine units.
Traditionally, AT&T troff drivers use a line thickness
proportional to the current point size; drivers should
continue to do this if no Dt command has been given, or if
a Dt command has been given with a negative value of n. A
zero value of n selects the smallest available line
thickness.
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
\D'c x1 y1 x2 y2 ... xn yn'
where c is not one of c, e, l, a, or ~, AT&T troff treats each of
the xi as a horizontal quantity, and each of the yi as a vertical
quantity and assumes that the width of the drawn object is in=Σ1xi,
and that the height is in=Σ1yi. (The assumption about the height
can be seen by examining the st and sb registers after using such
a D command in a \w escape sequence). This rule also holds for
all the original drawing commands with the exception of De. For
the sake of compatibility GNU troff also follows this rule, even
though it produces an ugly result in the case of the Dt and Df,
and, to a lesser extent, DE commands. Thus after executing a
D command of the form
Dc x1 y1 x2 y2 ... xn yn\n
the current position should be increased by (in=Σ1xi,in=Σ1yi).
Another set of extensions is
DFc cyan magenta yellow\n
DFd\n
DFg gray\n
DFk cyan magenta yellow black\n
DFr red green blue\n
Set the color components of the filling color similar to
the m commands above.
The current position isn't changed by those colour commands
(contrary to Df).
Device control commands
There is a continuation convention which permits the argument to
the x X command to contain newlines: when outputting the argument
to the x X command, GNU troff follows each newline in the
argument with a + character (as usual, it terminates the entire
argument with a newline); thus if the line after the line
containing the x X command starts with +, then the newline ending
the line containing the x X command should be treated as part of
the argument to the x X command, the + should be ignored, and the
part of the line following the + should be treated like the part
of the line following the x X command.
The first three output commands are guaranteed to be:
x T device
x res n h v
x init
