groff_font(5) — Linux manual page

Name | Description |

DESC file format | Font description file format | Files | See also | COLOPHON

groff_font(5)              File Formats Manual             groff_font(5)

Name         top

       groff_font - GNU roff device and font description files

Description         top

       The groff font and output device description formats are slight
       extensions of those used by AT&T device-independent troff.  In
       distinction to the AT&T implementation, groff lacks a binary
       format; all files are text files.  (Plan 9 troff has also
       abandoned the binary format.)  The device and font description
       files for a device name are stored in a devname directory.  The
       device description file is called DESC, and, for each font
       supported by the device, a font description file is called f,
       where f is usually an abbreviation of a font's name and/or style.
       For example, the ps (PostScript) device has groff font
       description files for Times roman (TR) and Zapf Chancery Medium
       italic (ZCMI), among many others, while the utf8 device (for
       terminals) has only font descriptions for the roman, italic,
       bold, and bold-italic styles (R, I, B, and BI, respectively).

       Device and font description files are read by the formatter,
       troff, and by output drivers.  The programs typically delegate
       these files' processing to an internal library, libgroff,
       ensuring their consistent interpretation.

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

       hor n  The horizontal motion quantum is n basic units.
              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(1), but under other
              systems (notably Cygwin) it might be set to another name.
              The grohtml(1) 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 A0A7, B0B7, C0C7,
              and D0D7; the U.S. formats 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
              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 other form.  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).

              Direct 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 the print spooler.  If omitted, groff's -l
              and -L options 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 a 0.
              Each si can also be a range of sizes mn.  The list can
              extend over more than one line.

       sizescale n
              A typographical point is subdivided into n scaled points.
              The default is 1.

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

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

              The output device supports the complete Unicode
              repertoire.  This directive is useful only for devices
              which 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

              The utf8, html, and xhtml output devices use this

       unitwidth n
              Quantities in the font description files are in basic
              units for fonts whose type size is n scaled points.

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

              troff should encode named glyphs inside device control
              commands.  The grohtml driver uses this directive.

       vert n The vertical motion quantum is n basic units.  Vertical
              quantities are rounded to multiples of n.

              This directive and the rest of 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.

       troff recognizes but ignores the directives spare1, spare2, and

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

Font description file format         top

       On typesetting output devices, each font is typically available
       at multiple sizes.  While paper measurements in the device
       description file are in absolute units, measurements applicable
       to fonts must be proportional to the type size.  groff achieves
       this using the precedent set by AT&T device-independent troff:
       one font size is chosen as a norm, and all others are scaled
       linearly relative to that basis.  The “unit width” is the number
       of basic units per point when the font is rendered at this
       nominal size.

       For instance, groff's lbp device uses a unitwidth of 800.  Its
       Times roman font (“TR”) has a spacewidth of 833; this is also the
       width of its comma, period, centered period, and mathematical
       asterisk, while its “M” is 2,963 basic units.  Thus, an “M” on
       the lbp device is 2,963 basic units wide at a notional type size
       of 800 points.  (800-point type is not practical for most
       purposes, but using it enables the quantities in the font
       description files to be expressed as integers.)

       A font description file has two sections.  The first is a
       sequence of directives, and is parsed similarly to the DESC file
       described above.  Except for the directive names that begin the
       second section, their ordering is immaterial.  Later directives
       of the same name override earlier ones, spaces and tabs are
       handled in the same way, and the same comment syntax is
       supported.  Empty lines are ignored throughout.

       name F The name of the font is F.  “DESC” is an invalid font
              name.  Simple integers are valid, but their use is
              discouraged.  (groff requests and escape sequences
              interpret non-negative integers as mounting positions
              instead.  Further, a font named “0” cannot be
              automatically mounted by the fonts directive of a DESC

       spacewidth n
              The width of an unadjusted inter-word space is n basic

       The directives above must appear in the first section; those
       below are optional.

       slant n
              The font's glyphs have a slant of n degrees; a positive n
              slants in the direction of text flow.

       ligatures lig1 ... lign [0]
              Glyphs lig1, ..., lign are ligatures; possible ligatures
              are ff, fi, fl, ffi, and ffl.  For compatibility with
              other troff implementations, the list of ligatures may be
              terminated with a 0.  The list of ligatures must not
              extend over more than one line.

              The font is special: when a glyph is requested that is not
              present in the formatter's currently selected font, the
              glyph is sought in any mounted fonts that bear this

       Other directives in this section are ignored by troff, but may be
       used by postprocessors to obtain further information about the

       The second section contains one or two subsections.  These can
       appear in either order; the first one encountered commences the
       second section.  Each starts with a directive on a line by
       itself.  A charset subsection is mandatory unless the associated
       DESC file contains the unicode directive.  Another subsection,
       kernpairs, is optional.

       The directive charset starts the character set subsection.  (On
       typesetters, this directive is misnamed since it starts a list of
       glyphs, not characters.)  It precedes a series of glyph
       descriptions, one per line.  Each such glyph description
       comprises a set of fields separated by spaces or tabs and
       organized as follows.

              name metrics type code [entity-name] [-- comment]

       name identifies the glyph: a printable character c corresponds to
       the troff ordinary character c, and a multi-character sequence
       not beginning with \, corresponds to the GNU troff special
       character escape sequence “\[name]”.  A name consisting of three
       minus signs, “---”, indicates that the glyph is unnamed: such
       glyphs can be accessed only by the \N escape sequence in troff.
       A special character named “---” can still be defined using .char
       and similar requests.  The name\-” defines the minus sign
       glyph.  Finally, name can be the horizontal motion escape
       sequences, \| and \^ (“thin” and “hair” spaces, respectively), in
       which case only the width metric described below is applied; a
       font can thus customize the widths of these spaces.

       The form of the metrics field is as follows (on one line; it may
       be broken here for readability).


       There must not be any spaces, tabs, or newlines between these
       subfields, which are in basic units expressed as decimal
       integers.  Unspecified subfields default to 0.  Since there is no
       associated binary format, these values are not required to fit
       into the C language data type char as they are in AT&T device-
       independent troff.

       The width subfield gives the width of the glyph.  The height
       subfield gives the height of the glyph (upwards is positive); if
       a glyph 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 glyph, that is, the distance below the
       baseline to which the glyph extends (downwards is positive); if a
       glyph does not extend below the baseline, it should be given a
       zero depth, rather than a negative depth.  Italic corrections are
       relevant to glyphs in italic or oblique styles.  The italic-
       correction is the amount of space that should be added after an
       oblique glyph to be followed immediately by an upright glyph.
       The left-italic-correction is the amount of space that should be
       added before an oblique glyph to be preceded immediately by an
       upright glyph.  The subscript-correction is the amount of space
       that should be added after an oblique glyph to be followed by a
       subscript; it should be less than the italic correction.

       For fonts used with typesetters, the type field gives a featural
       description of the glyph: it is a bit mask recording whether the
       glyph is an ascender, descender, both, or neither.  When a \w
       escape sequence is interpolated, these values are bitwise or-ed
       together for each glyph and stored in the ct register.  In font
       descriptions for terminals, all glyphs might have a type of zero,
       regardless of their appearance.

       0      means the glyph lies entirely between the baseline and a
              horizontal line at the “x-height” of the font, as with
              “a”, “c”, and “x”;

       1      means the glyph descends below the baseline, like “p”;

       2      means the glyph ascends above the font's x-height, like
              “A” or “b”); and

       3      means the glyph is both an ascender and a descender—this
              is true of parentheses in some fonts.

       The code field gives a numeric identifier that the postprocessor
       uses to render the glyph.  The glyph can be specified to troff
       using this code by means of the \N escape sequence.  The code can
       be any integer (that is, any integer parsable by the C standard
       library's strtol(3) function).

       The entity-name field defines an identifier for the glyph that
       the postprocessor uses to print the troff glyph name.  This field
       is optional; it was introduced so that the grohtml output driver
       could encode its character set.  For example, the glyph \[Po] is
       represented by “£” in HTML 4.0.  For efficiency, these data
       are now compiled directly into grohtml.  grops uses the field to
       build sub-encoding arrays for PostScript fonts containing more
       than 256 glyphs.

       Anything on the line after the entity-name field or “--” is
       ignored.  When afmtodit generates font description files for
       gropdf(1) and grops(1), it writes the UTF-16 code for the
       character to the comment field.

       A line in the charset section can also have the form
              name "
       identifying name as another name for the glyph mentioned in the
       preceding line.  Such aliases can be chained.

       The directive kernpairs starts a list of kerning adjustments to
       be made to adjacent glyph pairs from this font.  It contains a
       sequence of lines formatted as follows.
              g1 g2 n
       The foregoing means that when glyph g1 is typeset immediately
       before g2, the space between them should be increased by n.  Most
       kerning pairs should have a negative value for n.

Files         top

              describes the output device name.

              describes the font known as F on device name.

See also         top

       Groff: The GNU Implementation of troff, by Trent A. Fisher and
       Werner Lemberg, is the primary groff manual.  You can browse it
       interactively with “info groff”.

       “Troff User's Manual” by Joseph F. Ossanna, 1976 (revised by
       Brian W. Kernighan, 1992), AT&T Bell Laboratories Computing
       Science Technical Report No. 54, widely called simply “CSTR #54”,
       documents the language, device and font description file formats,
       and device-independent output format referred to collectively in
       groff documentation as “AT&T troff”.

       “A Typesetter-independent TROFF” by Brian W. Kernighan, 1982,
       AT&T Bell Laboratories Computing Science Technical Report No. 97,
       provides additional insights into the device and font description
       file formats and device-independent output format.

       groff(1), subsection “Utilities”, lists programs available for
       describing fonts in a variety of formats such that groff output
       drivers can use them.

       troff(1) documents the default device and font description file
       search path.

       groff_out(5), addftinfo(1)

COLOPHON         top

       This page is part of the groff (GNU troff) project.  Information
       about the project can be found at 
       ⟨⟩.  If you have a bug report
       for this manual page, see ⟨⟩.
       This page was obtained from the project's upstream Git repository
       ⟨⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-06-10.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

groff   6 June 2024                 groff_font(5)