File: groff.info,  Node: DESC File Format,  Next: Font Description File Format,  Prev: Device_and_Font_Description_Files.php">Device and Font Description Files,  Up: Device_and_Font_Description_Files.php">Device and Font Description Files

6.2.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.  All horizontal
     quantities are rounded 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'.  *Note 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'
     Quantities in the font description files are in basic units for
     fonts whose type size is N scaled points.

'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 inside device control
     commands; see *note Postprocessor Access::.  The 'grohtml' driver
     uses this directive.

'vert N'
     The vertical motion quantum is N basic units.  All vertical
     quantities are rounded 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.