--- name: "groff_font" section: "5" platform: "linux" package: "groff" version: "1.24.2-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/groff_font" --- # groff\_font(5) GNU roff device and font description files ## 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)](/gs/1.md), but under other systems (notably Cygwin) it might be set to another name. The [*grohtml*(1)](/grohtml/1.md) 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)](/strtol/3.md) 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 “**£**” 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)](/gropdf/1.md) and [*grops*(1)](/grops/1.md), 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/share/groff/1.24.2/font/dev*name*/DESC* describes the output device *name*. - */usr/share/groff/1.24.2/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)](/groff/1.md), subsection “Utilities”, lists programs available for describing fonts in a variety of formats such that *groff* output drivers can use them. [*troff*(1)](/troff/1.md) documents the default device and font description file search path. [*groff\_out*(5)](/groff_out/5.md), [*addftinfo*(1)](/addftinfo/1.md)