1groff_font(5) File Formats Manual groff_font(5)
2
6 groff_font - GNU roff device and font description files
7
9 The groff font and output device description formats are slight exten‐
10 sions of those used by AT&T device-independent troff. In distinction
11 to the AT&T implementation, groff lacks a binary format; all files are
12 text files. (Plan 9 troff has also abandoned the binary format.) The
13 device and font description files for a device name are stored in a de‐
14 vname directory. The device description file is called DESC, and, for
15 each font supported by the device, a font description file is called f,
16 where f is usually an abbreviation of a font's name and/or style. For
17 example, the ps (PostScript) device has groff font description files
18 for Times roman (TR) and Zapf Chancery Medium italic (ZCMI), among many
19 others, while the utf8 device (for terminal emulators) has only font
20 descriptions for the roman, italic, bold, and bold-italic styles (R, I,
21 B, and BI, respectively).
22 Device and font description files are read by the formatter, troff, and
24 by output drivers. The programs typically delegate these files' pro‐
25 cessing to an internal library, libgroff, ensuring their consistent in‐
26 terpretation.
27
29 The DESC file contains a series of directives; each begins a line.
30 Their order is not important, with two exceptions: (1) the res direc‐
31 tive must precede any papersize directive; and (2) the charset direc‐
32 tive must come last (if at all). If a directive name is repeated,
33 later entries in the file override previous ones (except that the paper
34 dimensions are computed based on the res directive last seen when
35 papersize is encountered). Spaces and/or tabs separate words and are
36 ignored at line boundaries. Comments start with the “#” character and
37 extend to the end of a line. Empty lines are ignored.
38 family fam
40 The default font family is fam.
41 fonts n F1 ... Fn
43 Fonts F1, ..., Fn are mounted at font positions m+1, ..., m+n
44 where m is the number of styles (see below). This directive may
45 extend over more than one line. A font name of 0 causes no font
46 to be mounted at the corresponding position.
47 hor n The horizontal motion quantum is n basic units. Horizontal
49 quantities are rounded to multiples of n.
50 image_generator program
52 Use program to generate PNG images from PostScript input. Under
53 GNU/Linux, this is usually gs(1), but under other systems (no‐
54 tably Cygwin) it might be set to another name. The grohtml(1)
55 driver uses this directive.
56 paperlength n
58 The vertical dimension of the output medium is n basic units
59 (deprecated: use papersize instead).
60 papersize format-or-dimension-pair-or-file-name ...
62 The dimensions of the output medium are as according to the ar‐
63 gument, which is either a standard paper format, a pair of di‐
64 mensions, or the name of a plain text file containing either of
65 the foregoing. Recognized paper formats are the ISO and DIN
66 formats A0–A7, B0–B7, C0–C7, and D0–D7; the U.S. formats letter,
67 legal, tabloid, ledger, statement, and executive; and the enve‐
68 lope formats com10, monarch, and DL. Matching is performed
69 without regard for lettercase.
70 Alternatively, the argument can be a custom paper format
72 length,width (with no spaces before or after the comma). Both
73 length and width must have a unit appended; valid units are “i”
74 for inches, “c” for centimeters, “p” for points, and “P” for pi‐
75 cas. Example: “12c,235p”. An argument that starts with a digit
76 is always treated as a custom paper format.
77 Finally, the argument can be a file name (e.g., /etc/papersize);
79 if the file can be opened, the first line is read and a match
80 attempted against each other form. No comment syntax is sup‐
81 ported.
82 More than one argument can be specified; each is scanned in turn
84 and the first valid paper specification used.
85 paperwidth n
87 The horizontal dimension of the output medium is n basic units
88 (deprecated: use papersize instead).
89 pass_filenames
91 Direct troff to emit the name of the source file being pro‐
92 cessed. This is achieved with the intermediate output command
93 “x F”, which grohtml interprets.
94 postpro program
96 Use program as the postprocessor.
97 prepro program
99 Use program as a preprocessor. The html and xhtml output de‐
100 vices use this directive.
101 print program
103 Use program as the print spooler. If omitted, groff's -l and -L
104 options are ignored.
105 res n The device resolution is n basic units per inch.
107 sizes s1 ... sn 0
109 The device has fonts at s1, ..., sn scaled points (see below).
110 The list of sizes must be terminated by a 0. Each si can also
111 be a range of sizes m–n. The list can extend over more than one
112 line.
113 sizescale n
115 A typographical point is subdivided into n scaled points. The
116 default is 1.
117 styles S1 ... Sm
119 The first m font mounting positions are associated with styles
120 S1, ..., Sm.
121 tcommand
123 The postprocessor can handle the t and u intermediate output
124 commands.
125 unicode
127 The output device supports the complete Unicode repertoire.
128 This directive is useful only for devices which produce charac‐
129 ter entities instead of glyphs.
130 If unicode is present, no charset section is required in the
132 font description files since the Unicode handling built into
133 groff is used. However, if there are entries in a font descrip‐
134 tion file's charset section, they either override the default
135 mappings for those particular characters or add new mappings
136 (normally for composite characters).
137 The utf8, html, and xhtml output devices use this directive.
139 unitwidth n
141 Quantities in the font description files are in basic units for
142 fonts whose type size is n scaled points.
143 unscaled_charwidths
145 Make the font handling module always return unscaled glyph
146 widths. The grohtml driver uses this directive.
147 use_charnames_in_special
149 troff should encode named glyphs inside device control commands.
150 The grohtml driver uses this directive.
151 vert n The vertical motion quantum is n basic units. Vertical quanti‐
153 ties are rounded to multiples of n.
154 charset
156 This directive and the rest of the file are ignored. It is rec‐
157 ognized for compatibility with other troff implementations. In
158 GNU troff, character set repertoire is described on a per-font
159 basis.
160 troff recognizes but ignores the directives spare1, spare2, and
162 biggestfont.
163 The res, unitwidth, fonts, and sizes lines are mandatory. Directives
165 not listed above are ignored by troff but may be used by postprocessors
166 to obtain further information about the device.
167
169 On typesetting output devices, each font is typically available at mul‐
170 tiple sizes. While paper measurements in the device description file
171 are in absolute units, measurements applicable to fonts must be propor‐
172 tional to the type size. groff achieves this using the precedent set
173 by AT&T device-independent troff: one font size is chosen as a norm,
174 and all others are scaled linearly relative to that basis. The “unit
175 width” is the number of basic units per point when the font is rendered
176 at this nominal size.
177 For instance, groff's lbp device uses a unitwidth of 800. Its Times
179 roman font (“TR”) has a spacewidth of 833; this is also the width of
180 its comma, period, centered period, and mathematical asterisk, while
181 its “M” is 2,963 basic units. Thus, an “M” on the lbp device is 2,963
182 basic units wide at a notional type size of 800 points. (800-point
183 type is not practical for most purposes, but using it enables the quan‐
184 tities in the font description files to be expressed as integers.)
185 A font description file has two sections. The first is a sequence of
187 directives, and is parsed similarly to the DESC file described above.
188 Except for the directive names that begin the second section, their or‐
189 dering is immaterial. Later directives of the same name override ear‐
190 lier ones, spaces and tabs are handled in the same way, and the same
191 comment syntax is supported. Empty lines are ignored throughout.
192 name F The name of the font is F. “DESC” is an invalid font name.
194 Simple integers are valid, but their use is discouraged. (groff
195 requests and escape sequences interpret non-negative font names
196 as mounting positions instead. Further, a font named “0” cannot
197 be automatically mounted by the fonts directive of a DESC file.)
198 spacewidth n
200 The width of an unadjusted inter-word space is n basic units.
201 The directives above must appear in the first section; those below are
203 optional.
204 slant n
206 The font's glyphs have a slant of n degrees; a positive n slants
207 in the direction of text flow.
208 ligatures lig1 ... lign [0]
210 Glyphs lig1, ..., lign are ligatures; possible ligatures are ff,
211 fi, fl, ffi, and ffl. For compatibility with other troff imple‐
212 mentations, the list of ligatures may be terminated with a 0.
213 The list of ligatures must not extend over more than one line.
214 special
216 The font is special: when a glyph is requested that is not
217 present in the current font, it is sought in any mounted fonts
218 that bear this property.
219 Other directives in this section are ignored by troff, but may be used
221 by postprocessors to obtain further information about the font.
222 The second section contains one or two subsections. These can appear
224 in either order; the first one encountered commences the second sec‐
225 tion. Each starts with a directive on a line by itself. A charset
226 subsection is mandatory unless the associated DESC file contains the
227 unicode directive. Another subsection, kernpairs, is optional.
228 The directive charset starts the character set subsection. (For type‐
230 setter devices, this directive is misnamed since it starts a list of
231 glyphs, not characters.) It precedes a series of glyph descriptions,
232 one per line. Each such glyph description comprises a set of fields
233 separated by spaces or tabs and organized as follows.
234 name metrics type code [entity-name] [-- comment]
236 name identifies the glyph: if name is a printable character c, it cor‐
238 responds to the troff ordinary character c. If name is a multi-charac‐
239 ter sequence not beginning with \, it corresponds to the GNU troff spe‐
240 cial character escape sequence “\[name]”. A name consisting of three
241 minus signs, “---”, indicates that the glyph is unnamed: such glyphs
242 can be accessed only by the \N escape sequence in troff. A special
243 character named “---” can still be defined using .char and similar re‐
244 quests. The name “\-” defines the minus sign glyph. Finally, name can
245 be the horizontal motion escape sequences, \| and \^ (“thin” and “hair”
246 spaces, respectively), in which case only the width metric described
247 below is applied; a font can thus customize the widths of these spaces.
248 The form of the metrics field is as follows (on one line; it may be
250 broken here for readability).
251 width[,[height[,[depth[,[italic-correction[,[
253 left-italic-correction[,[subscript-correction]]]]]]]]]]
254 There must not be any spaces, tabs, or newlines between these sub‐
256 fields, which are in basic units expressed as decimal integers. Un‐
257 specified subfields default to 0. Since there is no associated binary
258 format, these values are not required to fit into the C language data
259 type char as they are in AT&T device-independent troff.
260 The width subfield gives the width of the glyph. The height subfield
262 gives the height of the glyph (upwards is positive); if a glyph does
263 not extend above the baseline, it should be given a zero height, rather
264 than a negative height. The depth subfield gives the depth of the
265 glyph, that is, the distance below the baseline to which the glyph ex‐
266 tends (downwards is positive); if a glyph does not extend below the
267 baseline, it should be given a zero depth, rather than a negative
268 depth. Italic corrections are relevant to glyphs in italic or oblique
269 styles. The italic-correction is the amount of space that should be
270 added after an oblique glyph to be followed immediately by an upright
271 glyph. The left-italic-correction is the amount of space that should
272 be added before an oblique glyph to be preceded immediately by an up‐
273 right glyph. The subscript-correction is the amount of space that
274 should be added after an oblique glyph to be followed by a subscript;
275 it should be less than the italic correction.
276 For fonts used with typesetting devices, the type field gives a featu‐
278 ral description of the glyph: it is a bit mask recording whether the
279 glyph is an ascender, descender, both, or neither. When a \w escape
280 sequence is interpolated, these values are bitwise or-ed together for
281 each glyph and stored in the ct register. In font descriptions for
282 terminal devices, all glyphs might have a type of zero, regardless of
283 their appearance.
284 0 means the glyph lies entirely between the baseline and a hori‐
286 zontal line at the “x-height” of the font, as with “a”, “c”, and
287 “x”;
288 1 means the glyph descends below the baseline, like “p”;
290 2 means the glyph ascends above the font's x-height, like “A” or
292 “b”); and
293 3 means the glyph is both an ascender and a descender—this is true
295 of parentheses in some fonts.
296 The code field gives a numeric identifier that the postprocessor uses
298 to render the glyph. The glyph can be specified to troff using this
299 code by means of the \N escape sequence. The code can be any integer
300 (that is, any integer parsable by the C standard library's strtol(3)
301 function).
302 The entity-name field defines an identifier for the glyph that the
304 postprocessor uses to print the troff glyph name. This field is op‐
305 tional; it was introduced so that the grohtml output driver could en‐
306 code its character set. For example, the glyph \[Po] is represented by
307 “£” in HTML 4.0. For efficiency, these data are now compiled di‐
308 rectly into grohtml. grops uses the field to build sub-encoding arrays
309 for PostScript fonts containing more than 256 glyphs. Anything on the
310 line after the entity-name field or “--” is ignored.
311 A line in the charset section can also have the form
313 name "
314 identifying name as another name for the glyph mentioned in the preced‐
315 ing line. Such aliases can be chained.
316 The directive kernpairs starts a list of kerning adjustments to be made
318 to adjacent glyph pairs from this font. It contains a sequence of
319 lines formatted as follows.
320 g1 g2 n
321 The foregoing means that when glyph g1 is typeset immediately before
322 g2, the space between them should be increased by n. Most kerning
323 pairs should have a negative value for n.
324
326 /usr/share/groff/1.23.0/font/devname/DESC
327 describes the output device name.
328 /usr/share/groff/1.23.0/font/devname/F
330 describes the font known as F on device name.
331
333 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
334 Lemberg, is the primary groff manual. You can browse it interactively
335 with “info groff”.
336 “Troff User's Manual” by Joseph F. Ossanna, 1976 (revised by Brian W.
338 Kernighan, 1992), AT&T Bell Laboratories Computing Science Technical
339 Report No. 54, widely called simply “CSTR #54”, documents the language,
340 device and font description file formats, and device-independent output
341 format referred to collectively in groff documentation as “AT&T troff”.
342 “A Typesetter-independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell
344 Laboratories Computing Science Technical Report No. 97, provides addi‐
345 tional insights into the device and font description file formats and
346 device-independent output format.
347 groff(1), subsection “Utilities”, lists programs available for describ‐
349 ing fonts in a variety of formats such that groff output drivers can
350 use them.
351 troff(1) documents the default device and font description file search
353 path.
354 groff_out(5), addftinfo(1)
356groff 1.23.0 2 November 2023 groff_font(5)