1GROFF_FONT(5)                 File Formats Manual                GROFF_FONT(5)
2
3
4

NAME

6       groff_font - format of groff device and font description files
7

DESCRIPTION

9       The groff font format is roughly a superset of the ditroff font format.
10       The font files for device name  are  stored  in  a  directory  devname.
11       There  are two types of file: a device description file called DESC and
12       for each font F, a font file called F.  These are  text  files;  unlike
13       the ditroff font format, there is no associated binary format.
14
15   DESC file format
16       The  DESC  file can contain the following types of line as shown below.
17       Later entries in the file override previous values.
18
19       Empty lines are ignored.
20
21       charset
22              This line and everything following in the file are ignored.   It
23              is allowed for the sake of backwards compatibility.
24
25       family fam
26              The default font family is fam.
27
28       fonts n F1 F2 F3 ... Fn
29              Fonts  F1,  ...,  Fn are mounted in the font positions m+1, ...,
30              m+n where m is the number of styles.  This  command  may  extend
31              over  more than one line.  A font name of 0 causes no font to be
32              mounted on the corresponding font position.
33
34       hor n  The horizontal resolution is n machine units.
35
36       image_generator string
37              Needed for grohtml only.  It specifies the program  to  generate
38              PNG  images from PostScript input.  Under GNU/Linux this is usu‐
39              ally gs but under other systems (notably cygwin) it might be set
40              to another name.
41
42       paperlength n
43              The  physical vertical dimension of the output medium in machine
44              units.  This isn't used by troff itself but by  output  devices.
45              Deprecated.  Use papersize instead.
46
47       papersize string
48              Select  a paper size.  Valid values for string are the ISO paper
49              types A0–A7, B0–B7, C0–C7, D0–D7, DL, and  the  US  paper  types
50              letter, legal, tabloid, ledger, statement, executive, com10, and
51              monarch.  Case is not significant for string if it holds  prede‐
52              fined  paper  types.   Alternatively,  string can be a file name
53              (e.g. /etc/papersize); if the file can be  opened,  groff  reads
54              the  first  line  and tests for the above paper sizes.  Finally,
55              string can be a custom paper size in the format length,width (no
56              spaces  before and after the comma).  Both length and width must
57              have a unit appended; valid values are ‘i’ for inches,  ‘c’  for
58              centimeters,  ‘p’  for  points,  and  ‘P’  for  picas.  Example:
59              12c,235p.  An argument which  starts  with  a  digit  is  always
60              treated  as a custom paper format.  papersize sets both the ver‐
61              tical and horizontal dimension of the output medium.
62
63              More than one argument can be specified; groff scans  from  left
64              to right and uses the first valid paper specification.
65
66       paperwidth n
67              The  physical  horizontal  dimension of the output medium in ma‐
68              chine units.  Deprecated.  Use papersize  instead.   This  isn't
69              used by troff itself but by output devices.
70
71       pass_filenames
72              Make troff tell the driver the source file name being processed.
73              This is achieved by another tcommand: F filename.
74
75       postpro program
76              Use program as the postprocessor.
77
78       prepro program
79              Call program as a preprocessor.
80
81       print program
82              Use program as the spooler program for  printing.   If  omitted,
83              the -l and -L options of groff are ignored.
84
85       res n  There are n machine units per inch.
86
87       sizes s1 s2 ... sn 0
88              This  means  that the device has fonts at s1, s2, ..., sn scaled
89              points.  The list of sizes must be terminated by a 0.   Each  si
90              can also be a range of sizes mn.  The list can extend over more
91              than one line.
92
93       sizescale n
94              The scale factor for point sizes.  By default this has  a  value
95              of  1.  One scaled point is equal to one point/n.  The arguments
96              to the unitwidth and sizes commands are given in scaled points.
97
98       styles S1 S2 ... Sm
99              The first m font positions are associated with styles  S1,  ...,
100              Sm.
101
102       tcommand
103              This  means that the postprocessor can handle the t and u output
104              commands.
105
106       unicode
107              Indicate that the output device supports  the  complete  Unicode
108              repertoire.  Useful only for devices which produce character en‐
109              tities instead of glyphs.
110
111              If unicode is present, no charset section  is  required  in  the
112              font  description  files  since  the Unicode handling built into
113              groff is used.  However, if there are entries in a charset  sec‐
114              tion,  they  either override the default mappings for those par‐
115              ticular characters or add new mappings (normally  for  composite
116              characters).
117
118              This is used for -Tutf8, -Thtml, and -Txhtml.
119
120       unitwidth n
121              Quantities  in  the  font  files  are given in machine units for
122              fonts whose point size is n scaled points.
123
124       unscaled_charwidths
125              Make the font  handling  module  always  return  unscaled  glyph
126              widths.  Needed for the grohtml device.
127
128       use_charnames_in_special
129              This command indicates that troff should encode named glyphs in‐
130              side special commands.
131
132       vert n The vertical resolution is n machine units.
133
134       The res, unitwidth, fonts, and sizes lines  are  compulsory.   Not  all
135       commands  in  the  DESC file are used by troff itself; some of the key‐
136       words (or even additional ones) are used by postprocessors to store ar‐
137       bitrary information about the device.
138
139       Here a list of obsolete keywords which are recognized by groff but com‐
140       pletely ignored: spare1, spare2, biggestfont.
141
142   Font file format
143       A font file has two sections; empty lines are ignored in both of them.
144
145       The first section is a sequence of lines each containing a sequence  of
146       blank  delimited words; the first word in the line is a key, and subse‐
147       quent words give a value for that key.
148
149       ligatures lig1 lig2 ... lign [0]
150              Glyphs lig1, lig2, ..., lign are ligatures;  possible  ligatures
151              are  ff, fi, fl, ffi, and ffl.  For backwards compatibility, the
152              list of ligatures may be terminated with a 0.  The list of liga‐
153              tures may not extend over more than one line.
154
155       name F The name of the font is F.
156
157       slant n
158              The  glyphs  of  the  font have a slant of n degrees.  (Positive
159              means forward.)
160
161       spacewidth n
162              The normal width of a space is n.
163
164       special
165              The font is special; this means that when a glyph  is  requested
166              that  is  not present in the current font, it is searched for in
167              any special fonts that are mounted.
168
169       Other commands are ignored by troff but may be used  by  postprocessors
170       to store arbitrary information about the font in the font file.
171
172       The first section can contain comments which start with the # character
173       and extend to the end of a line.
174
175       The second section contains one or two subsections.  It must contain  a
176       charset  subsection  and  it  may  also contain a kernpairs subsection.
177       These subsections can appear in any order.  Each subsection starts with
178       a word on a line by itself.
179
180       The  word  charset  starts the charset subsection.  The charset line is
181       followed by a sequence of lines.  Each line gives information  for  one
182       glyph.   A  line  comprises  a  number of fields separated by blanks or
183       tabs.  The format is
184
185              name metrics type code [entity_name] [-- comment]
186
187       name identifies the glyph: if name is a single glyph c then  it  corre‐
188       sponds  to the groff input character c; if it is of the form \c where c
189       is a single character, then it corresponds  to  the  special  character
190       \[c];  otherwise  it  corresponds to the groff input character \[name].
191       If it is exactly two characters xx it can be  entered  as  \(xx.   Note
192       that single-letter special characters can't be accessed as \c; the only
193       exception is ‘\-’ which is identical to ‘\[-]’.  The name ---  is  spe‐
194       cial  and  indicates that the glyph is unnamed; such glyphs can only be
195       used by means of the \N escape sequence in troff.
196
197       The type field gives the glyph type:
198
199       1      means the glyph has a descender, for example, ‘p’;
200
201       2      means the glyph has an ascender, for example, ‘b’;
202
203       3      means the glyph has both an ascender and a descender, for  exam‐
204              ple, ‘(’.
205
206       The code field gives the code which the postprocessor uses to print the
207       glyph.  The glyph can also be input to groff using this code  by  means
208       of  the \N escape sequence.  The code can be any integer.  If it starts
209       with a 0 it is interpreted as octal; if it starts with 0x or 0X  it  is
210       interpreted as hexadecimal.  Note, however, that the \N escape sequence
211       only accepts a decimal integer.
212
213       The entity_name field gives an ASCII string identifying the glyph which
214       the postprocessor uses to print that glyph.  This field is optional and
215       is currently used by grops to build sub-encoding arrays  for  PS  fonts
216       containing  more than 256 glyphs.  (It has also been used for grohtml's
217       entity names but for efficiency reasons this data is now  compiled  di‐
218       rectly into grohtml.)
219
220       Anything on the line after the encoding field or ‘--’ are ignored.
221
222       The  metrics field has the form (in one line; it is broken here for the
223       sake of readability):
224
225              width[,height[,depth[,italic-correction
226              [,left-italic-correction[,subscript-correction]]]]]
227
228       There must not be any spaces between  these  subfields.   Missing  sub‐
229       fields  are  assumed  to be 0.  The subfields are all decimal integers.
230       Since there is no associated binary format, these values  are  not  re‐
231       quired to fit into a variable of type char as they are in ditroff.  The
232       width subfields gives the width of  the  glyph.   The  height  subfield
233       gives  the  height  of the glyph (upwards is positive); if a glyph does
234       not extend above the baseline, it should be given a zero height, rather
235       than  a  negative  height.   The  depth subfield gives the depth of the
236       glyph, that is, the distance below the baseline to which the glyph  ex‐
237       tends  (downwards  is  positive);  if a glyph does not extend below the
238       baseline, it should be given a  zero  depth,  rather  than  a  negative
239       depth.   The  italic-correction subfield gives the amount of space that
240       should be added after the glyph when it is immediately to  be  followed
241       by  a  glyph  from  a  roman font.  The left-italic-correction subfield
242       gives the amount of space that should be added before the glyph when it
243       is  immediately  to be preceded by a glyph from a roman font.  The sub‐
244       script-correction gives the amount of space that should be added  after
245       a glyph before adding a subscript.  This should be less than the italic
246       correction.
247
248       A line in the charset section can also have the format
249
250              name "
251
252       This indicates that name is just another name for the  glyph  mentioned
253       in the preceding line.
254
255       The  word  kernpairs starts the kernpairs section.  This contains a se‐
256       quence of lines of the form:
257
258              c1 c2 n
259
260       This means that when glyph c1 appears next to glyph c2  the  space  be‐
261       tween them should be increased by n.  Most entries in kernpairs section
262       have a negative value for n.
263

FILES

265       /usr/share/groff/1.22.4/font/devname/DESC
266              Device description file for device name.
267
268       /usr/share/groff/1.22.4/font/devname/F
269              Font file for font F of device name.
270

SEE ALSO

272       groff_out(5), troff(1), addftinfo(1), afmtodit(1)
273
274       A man page name(n) of section n can be viewed either with
275              $ man n name
276       for text mode or
277              $ groffer n name
278       for graphical mode (default is PDF mode).
279
280
281
282groff 1.22.4                    20 January 2022                  GROFF_FONT(5)
Impressum