8. File formats

8.1 gtroff Output
8.2 Font Files

8.1 gtroff Output

This section describes the format output of GNU troff. The output format used by GNU troff is very similar to that used by UNIX device-independent troff (ditroff).

8.1.1 Output Format
8.1.2 Device Control
8.1.3 Drawing Functions
8.1.4 Line Continuation

8.1.1 Output Format

The output format is text based, as opposed to a binary format (like TeX DVI). The output format is 8-bit clean, thus single characters can have the eighth bit set, as can the names of fonts and special characters.

The output format consists of single command characters with attached parameters which are separated from subsequent text by whitespace or a newline.

The names of characters and fonts can be of arbitrary length; drivers should not assume that they will be only two characters long (as ditroff does).

When a character is to be printed, that character will always be in the current font. Unlike ditroff, it is not necessary for drivers to search special fonts to find a character.

Hn

Vn

hn

vn

cn

Cn

nnc

txxx

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.

This command is only allowed if the `tcommand' line is present in the `DESC' file.

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.

This command is only allowed if the `tcommand' line is present in the `DESC' file.

nab

pn

sn

The argument to the `s' command is in scaled points (units of points/n, where n is the argument to the `sizescale' command in the `DESC' file).

fn

x ... \n

Device control.

Dc x...\n

8.1.2 Device Control

The `x' command is normally followed by a letter or word indicating the function to perform, followed by white space separated arguments.

The first argument can be abbreviated to the first letter.

x init

x T

x res n h v

x H

The argument to the `x Height' command is also in scaled points.

The first three output commands are guaranteed to be:

x T device x res n h v x init

For example, the input

crunchy \fH\s+2frog\s0\fP!?

will produce

8.1.3 Drawing Functions

The `D' drawing command has been extended. These extensions will only be used by GNU pic if the `-x' option is given.

See section 5.23 Drawing Requests.

Df 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 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.

DC d

Draw a solid circle with a diameter of d with the leftmost point at the current position.

DE dx dy

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

Draw a polygon with. The first vertex is at the current position, the second vertex at an offset (dx1,dy1) from the current position, the second vertex at an offset (dx2,dy2) from the first vertex, and so on up to the n-th vertex. At the moment, GNU pic only uses this command to generate triangles and rectangles.

DP dx1 dy1 dx2 dy2 ... dxn dyn

Like Dp but draw a solid rather than outlined polygon.

Dt n

Set the current line thickness to 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 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 `~', UNIX troff will treat each of the x value as a horizontal quantity, and each of the y values as a vertical quantity and will assume that the width of the drawn object is sum if all x values, and that the height is the sum of all y values. (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 Df, Dt, and, to a lesser extent, DE commands. Thus after executing a D command of the form

Dc x1 y1 x2 y2 ... xn yn

the current position should be increased horizontally by the sum of all x values and vertically by the sum of all y values.

8.1.4 Line Continuation

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 will follow each newline in the argument with a `+' character (as usual, it will terminate 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.

8.2 Font Files

The gtroff font format is roughly a superset of the ditroff font format. Unlike the ditroff font format, there is no associated binary format; all files are text files. The font files for device name are stored in a directory `devname'. There are two types of file: a device description file called `DESC' and for each font f a font file called `f'.

8.2.1 `DESC' file format
8.2.2 Font file format

8.2.1 `DESC' file format

The `DESC' file can contain the following types of line:

res n

There are n machine units per inch.

hor n

The horizontal resolution is n machine units.

vert n

The vertical resolution is n machine units.

sizescale n

The scale factor for point sizes. By default this has a value of 1. One scaled point is equal to one point/n. The arguments to the unitwidth and sizes commands are given in scaled points. See section 5.18.2 Fractional Type Sizes, for more information.

unitwidth n

Quantities in the font files are given in machine units for fonts whose point size is n scaled points.

tcommand

This means that the postprocessor can handle the `t' and `u' output commands.

sizes s1 s2 ... sn 0

This means that the device has fonts at s1, s2, ... sn scaled points. The list of sizes must be terminated by a 0. Each si can also be a range of sizes m-n. The list can extend over more than one line.

styles S1 S2 ... Sm

The first m font positions will be associated with styles S1 ... Sm.

fonts n F1 F2 F3 ... Fn

Fonts F1 ... Fn will be mounted in the font positions m+1, ..., m+n where m is the number of styles. This command may extend over more than one line. A font name of 0 will cause no font to be mounted on the corresponding font position.

family fam

The default font family is fam.

charset

This line and everything following in the file are ignored. It is allowed for the sake of backwards compatibility.

The res, unitwidth, fonts and sizes lines are mandatory. Other commands are ignored by gtroff but may be used by postprocessors to store arbitrary information about the device in the `DESC' file.

8.2.2 Font file format

A font file has two sections. The first section is a sequence of lines each containing a sequence of blank delimited words; the first word in the line is a key, and subsequent words give a value for that key.

name f

The name of the font is f.

spacewidth n

The normal width of a space is n.

slant n

The characters of the font have a slant of n degrees. (Positive means forward.)

ligatures lig1 lig2 ... lign [0]

Characters lig1, lig2, ..., lign are ligatures; possible ligatures are `ff', `fi', `fl', `ffi' and `ffl'. For backwards compatibility, the list of ligatures may be terminated with a 0. The list of ligatures may not extend over more than one line.

special

The font is special; this means that when a character is requested that is not present in the current font, it will be searched for in any special fonts that are mounted.

Other commands are ignored by gtroff but may be used by postprocessors to store arbitrary information about the font in the font file.

The first section can contain comments which start with the `#' character and extend to the end of a line.

The second section contains one or two subsections. It must contain a charset subsection and it may also contain a kernpairs subsection. These subsections can appear in any order. Each subsection starts with a word on a line by itself.

The word charset starts the character set subsection. The charset line is followed by a sequence of lines. Each line gives information for one character. A line comprises a number of fields separated by blanks or tabs. The format is

name metrics type code comment

name identifies the character: If name is a single character c then it corresponds to the gtroff input character c; if it is of the form `\c' where c is a single character, then it corresponds to the gtroff input character \c; otherwise it corresponds to the groff input character `\[name]'. (If it is exactly two characters xx it can be entered as `\(xx'.) gtroff supports 8-bit characters; however some utilities have difficulties with eight-bit characters. For this reason, there is a convention that the name `charn' is equivalent to the single character whose code is n. For example, `char163' would be equivalent to the character with code 163 which is the pounds sterling sign in ISO Latin-1 character set. The name `---' is special and indicates that the character is unnamed; such characters can only be used by means of the \N escape sequence in gtroff.

The type field gives the character type:

1

the character has an descender, for example, `p';

2

the character has an ascender, for example, `b';

3

the character has both an ascender and a descender, for example, `('.

The code field gives the code which the postprocessor uses to print the character. The character can also be input to gtroff using this code by means of the \N escape sequence. The code can be any integer. If it starts with `0' it will be interpreted as octal; if it starts with `0x' or `0X' it will be interpreted as hexadecimal.

Anything on the line after the code field will be ignored.

The metrics field has the form:

width[,height[,depth[,italic_correction [,left_italic_correction[,subscript_correction]]]]]

There must not be any spaces between these subfields (it has been split here into two lines for better legibility only). Missing subfields are assumed to be 0. The subfields are all decimal integers. Since there is no associated binary format, these values are not required to fit into a variable of type `char' as they are in ditroff. The width subfield gives the width of the character. The height subfield gives the height of the character (upwards is positive); if a character does not extend above the baseline, it should be given a zero height, rather than a negative height. The depth subfield gives the depth of the character, that is, the distance below the lowest point below the baseline to which the character extends (downwards is positive); if a character does not extend below above the baseline, it should be given a zero depth, rather than a negative depth. The italic_correction subfield gives the amount of space that should be added after the character when it is immediately to be followed by a character from a Roman font. The left_italic_correction subfield gives the amount of space that should be added before the character when it is immediately to be preceded by a character from a Roman font. The subscript_correction gives the amount of space that should be added after a character before adding a subscript. This should be less than the italic correction.

A line in the charset section can also have the format

name "

This indicates that name is just another name for the character mentioned in the preceding line.

The word kernpairs starts the kernpairs section. This contains a sequence of lines of the form:

c1 c2 n

This means that when character c1 appears next to character c2 the space between them should be increased by n. Most entries in kernpairs section will have a negative value for n.