# groff_font

## Name



           groff_font - GNU _roff_ device and font description files
    


## Description



           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 _dev_ name 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 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
                  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_(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 **A0** –**A7** , **B0** –**B7** , **C0** –**C7** , and **D0** –**D7** ; 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).
    
           **pass_filenames**
                  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 _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**.
    
           **styles** _S1_ ... _Sm_
                  The first _m_ font 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 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
                  characters).
    
                  The **utf8** , **html** , and **xhtml** output devices use this
                  directive.
    
           **unitwidth** _n_
                  Arbitrary 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 glyph
                  widths.  The _grohtml_ driver uses this directive.
    
           **use_charnames_in_special**
                  _troff_ should encode special characters in arguments to
                  device extension commands.  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 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
           **biggestfont**.
    
           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



           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.
    
           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_ file.)
    
           **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.  (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 index_ [_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).
    
                  _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.  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 **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 _index_ field is an integer that uniquely identifies a glyph
           within the font; any integer is accepted as input, (that is, any
           integer parsable by the C standard library's _strtol_(3) function)
           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 _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 “**& pound;**” 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.
    
           A **charset-range** subsection works like the **charset** directive except
           that the glyph descriptions use a _name_ of the form **u** _AAAA_**..u** _FFFF_ ,
           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_.
    


## Files



           _/usr/local/share/groff/1.23.0/font/dev_ name _/DESC_
                  describes the output device _name_.
    
           _/usr/local/share/groff/1.23.0/font/dev_ name _/_ F
                  describes the font known as _F_ on device _name_.
    


## See also



           _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 page description language 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 page description language.
    
           _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)
    


* * *