# groff_font - GNU roff device and font description files - man(5) - [phpMan] [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown) File Formats Manual [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown) ## 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 bi‐ nary 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 terminal emulators) 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_, en‐ suring their consistent interpretation. _**DESC_ file format** The _DESC_ file contains a series of directives; each begins a line. Their order is not impor‐ tant, 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 sep‐ arate 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 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)](https://www.chedong.com/phpMan.php/man/gs/1/markdown), but under other systems (notably Cygwin) it might be set to another name. The [_grohtml_(1)](https://www.chedong.com/phpMan.php/man/grohtml/1/markdown) 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 con‐ taining 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. Ex‐ ample: “**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 com‐ ment 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 charac‐ ters). 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 glyph widths. The _grohtml_ driver uses this directive. ### use_charnames_in_special _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 mul‐ tiples of _n._ ### charset This directive and the rest of the file are ignored. It is recognized for compatibil‐ ity with other _troff_ implementations. In GNU _troff_, character set repertoire is de‐ scribed 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 pa‐ per measurements in the device description file are in absolute units, measurements applica‐ ble 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 mathe‐ matical 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 practi‐ cal 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 font names as mounting positions instead. Further, a font named “**0**” can‐ not be automatically mounted by the **fonts **directive of a _DESC_ file.) **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 ter‐ minated 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 _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. (For typesetter devices, this di‐ rective 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: 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 corre‐ sponds 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 de‐ fined using **.char **and similar requests. The _name_ “**\-**” defines the minus sign glyph. Fi‐ nally, _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 readabil‐ ity). _width_[**,**[_height_[**,**[_depth_[**,**[_italic-correction_[**,**[_left-italic-correction_[**,**[ _subscript-correction_]]]]]]]]]] 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 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 nei‐ ther. 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 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, 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)](https://www.chedong.com/phpMan.php/man/strtol/3/markdown) 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. 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 _/usr/share/groff/1.23.0/font/dev_name_/DESC_ describes the output device _name_. _/usr/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 out‐ put format referred to collectively in _groff_ documentation as “AT&T _troff_”. “A Typesetter-independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell Laboratories Comput‐ ing Science Technical Report No. 97, provides additional insights into the device and font description file formats and device-independent output format. [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown), subsection “Utilities”, lists programs available for describing fonts in a variety of formats such that _groff_ output drivers can use them. [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) documents the default device and font description file search path. [_groff_out_(5)](https://www.chedong.com/phpMan.php/man/groffout/5/markdown), [_addftinfo_(1)](https://www.chedong.com/phpMan.php/man/addftinfo/1/markdown) groff 1.23.0 31 March 2024 [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown)