6.1.1 DESC File Format

The DESC file contains a series of directives; each begins a line. Their order is not important, with two exceptions: (1) the res directive must precede any papersize directive; and (2) the charset directive must come last (if at all). If a directive name is repeated, later entries in the file override previous ones (except that the paper dimensions are computed based on the res directive last seen when papersize is encountered). Spaces and/or tabs separate words and are ignored at line boundaries. Comments start with the ‘#’ character and extend to the end of a line. Empty lines are ignored.

family fam

The default font family is fam.

fonts n F1 … Fn

Fonts F1, …, Fn are mounted at font positions m+1, …, m+n where m is the number of styles (see below). This directive may extend over more than one line. A font name of 0 causes no font to be mounted at the corresponding position.

hor n

The horizontal motion quantum is n basic units. Horizontal measurements round to multiples of n.

image_generator program

Use program to generate PNG images from PostScript input. Under GNU/Linux, this is usually gs, but under other systems (notably Cygwin) it might be set to another name. The grohtml driver uses this directive.

paperlength n

The vertical dimension of the output medium is n basic units (deprecated: use papersize instead).

papersize format-or-dimension-pair-or-file-name …

The dimensions of the output medium are as according to the argument, which is either a standard paper format, a pair of dimensions, or the name of a plain text file containing either of the foregoing.

Recognized paper formats are the ISO and DIN formats A0–A7, B0–B7, C0–C7, D0–D7; the U.S. paper types letter, legal, tabloid, ledger, statement, and executive; and the envelope formats com10, monarch, and DL. Matching is performed without regard for lettercase.

Alternatively, the argument can be a custom paper format in the format length,width (with no spaces before or after the comma). Both length and width must have a unit appended; valid units are ‘i’ for inches, ‘c’ for centimeters, ‘p’ for points, and ‘P’ for picas. Example: ‘12c,235p’. An argument that starts with a digit is always treated as a custom paper format.

Finally, the argument can be a file name (e.g., /etc/papersize); if the file can be opened, the first line is read and a match attempted against each of the other forms. No comment syntax is supported.

More than one argument can be specified; each is scanned in turn and the first valid paper specification used.

paperwidth n

The horizontal dimension of the output medium is n basic units (deprecated: use papersize instead).

pass_filenames

Direct GNU troff to emit the name of the source file being processed. This is achieved with the intermediate output command ‘x F’, which grohtml interprets.

postpro program

Use program as the postprocessor.

prepro program

Use program as a preprocessor. The html and xhtml output devices use this directive.

print program

Use program as a spooler program for printing. If omitted, the -l and -L options of groff are ignored.

res n

The device resolution is n basic units per inch.

sizes s1 … sn 0

The device has fonts at s1, …, sn scaled points (see below). The list of sizes must be terminated by 0. Each si can also be a range of sizes m–n. The list can extend over more than one line.

sizescale n

A typographical point is subdivided into n scaled points. The default is 1. See Using Fractional Type Sizes.

styles S1 … Sm

The first m mounting positions are associated with styles S1, …, Sm.

tcommand

The postprocessor can handle the ‘t’ and ‘u’ intermediate output commands.

unicode

The output device supports the complete Unicode repertoire. This directive is useful only for devices that produce character entities instead of glyphs.

If unicode is present, no charset section is required in the font description files since the Unicode handling built into groff is used. However, if there are entries in a font description file’s charset section, they either override the default mappings for those particular characters or add new mappings (normally for composite characters).

The utf8, html, and xhtml output devices use this directive.

unitwidth n

Arbitary basis with respect to which font metrics are proportionally scaled when rendering glyphs at a type size of one point.

unscaled_charwidths

Make the font handling module always return unscaled character widths. The grohtml driver uses this directive.

use_charnames_in_special

GNU troff should encode special characters in arguments to device extension commands; see Postprocessor Access. The grohtml driver uses this directive.

vert n

The vertical motion quantum is n basic units. Vertical measurements round to multiples of n.

charset

This line and everything following it in the file are ignored. It is recognized for compatibility with other troff implementations. In GNU troff, character set repertoire is described on a per-font basis.

GNU troff recognizes but ignores the directives spare1, spare2, and biggestfont.

The res, unitwidth, fonts, and sizes lines are mandatory. Directives not listed above are ignored by GNU troff but may be used by postprocessors to obtain further information about the device.