6.1.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. The font’s unit width establishes a numerical basis that permits all of its metrics to be expressed as integers if rendered at one point. When the formatter configures a type size, it scales the metrics linearly relative to that basis. The unit width has no inherent relationship to the device resolution, and the same division procedure applies to all font metrics. Observe that whatever unit might one select for the unit width, the division operation implied by scaling cancels it out, leaving a dimensionless quantity.

For instance, groff’s lbp device uses a unitwidth directive with an argument 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’ has a width of 2,963. Thus, an ‘M’ on the lbp device is 2,963 ÷ 800 times the unit width, or approximately 3.7. At a type size of 10 points, a Times roman ‘M’ is therefore 37 units wide.

$ groff -T lbp
.ps 10
.nr Mw \w'M'
.tm width of 'M' at 10 points=\n(Mw
    error→ width of 'M' at 10 points=37

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.¹⁹⁵

spacewidth n

The width of an unadjusted inter-word space is n, relative to the device’s unit width.

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 the document attempts to format a glyph that is not present in the formatter’s currently selected font, the glyph is sought in any mounted fonts that bear this property. Often, such fonts are unstyled, having no heavy (bold) or slanted (italic or oblique) variants.

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 to three subsections, which can appear in any order, and any of which starts 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.¹⁹⁶ 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 index [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]]]]]]]]]]

Spaces, tabs, and newlines are prohibited between these subfields, which are expressed as decimal integers (and have been split here into two lines only for better legibility). The unit of measure is that established by the unitwidth directive and scaled to the type size. 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, give it a zero height, not 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, give it a zero depth, not a negative depth. Italic corrections apply when upright and slanted (italic or oblique) styles are typeset adjacently. The italic-correction is the amount of space to add after a slanted glyph to be followed immediately by an upright glyph. The left-italic-correction is the amount of space to add before a slanted glyph to be preceded immediately by an upright glyph. The subscript-correction is the amount of space to add after a slanted 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 nr 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; 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 index field is an integer that uniquely identifies a glyph within the font; any integer is accepted as input,¹⁹⁷ but no practical font employs all possible values. An index is limited to the range of the system’s C language data type int. In a troff document, use the indexed character escape sequence \N to specify a glyph by index.

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.

A charset-range subsection works like the charset directive except that the glyph descriptions use a name of the form uAAAA..uFFFF, where AAAA and FFFF are hexadecimal digit sequences; the specified metrics then apply identically to all glyphs in the designated range.

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. The unit of measure is that established by the unitwidth directive and scaled to the type size. Most kerning pairs should have a negative value for n.