File: groff.info,  Node: Font Description File Format,  Prev: DESC File Format,  Up: Device and Font Description Files

6.2.2 Font Description File Format
----------------------------------

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.(1)  (*note Font
Description File Format-Footnote-1::)

   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.(2)  (*note Font
     Description File Format-Footnote-2::)

'spacewidth N'
     The width of an unadjusted inter-word space is N basic units.

   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.

'special'
     The font is "special": when a glyph is requested that is not
     present in the current font, it is sought in any mounted fonts that
     bear this property.

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

   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.(3)
(*note Font Description File Format-Footnote-3::) 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: if NAME is a printable character C, it
corresponds to the 'troff' ordinary character C.  If NAME is a
multi-character sequence not beginning with '\', it corresponds to the
GNU 'troff' special character escape sequence '\[NAME]'.  A name
consisting of three minus signs, '---', is special and 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 unbreakable one-sixth and
one-twelfth space escape sequences, '\|' and '\^' ("thin" and "hair"
spaces, respectively), in which case only the width metric described
below is interpreted; a font can thus customize the widths of these
spaces.

   The form of the METRICS field is as follows.

     WIDTH[','[HEIGHT[','[DEPTH[','[ITALIC-CORRECTION
       [','[LEFT-ITALIC-CORRECTION[','[SUBSCRIPT-CORRECTION]]]]]]]]]]

There must not be any spaces, tabs, or newlines between these
"subfields" (which have been split here into two lines only for better
legibility).  The subfields 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 (upward 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
(downward 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 typesetting devices, 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 'nr' register.  In font descriptions
for terminal devices, 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; typical examples are '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.  CODE can be any integer.(4)
(*note Font Description File Format-Footnote-4::)

   The ENTITY-NAME field defines an identifier for the glyph that the
postprocessor uses to print the GNU '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.

   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.