| blob | 8b9e3b40793ce0b2dc21499e67b05053679673c9 |
1 .ig \"-*- nroff -*-
2 Copyright (C) 1989-1995 Free Software Foundation, Inc.
4 Permission is granted to make and distribute verbatim copies of
5 this manual provided the copyright notice and this permission notice
6 are preserved on all copies.
8 Permission is granted to copy and distribute modified versions of this
9 manual under the conditions for verbatim copying, provided that the
10 entire resulting derived work is distributed under the terms of a
11 permission notice identical to this one.
13 Permission is granted to copy and distribute translations of this
14 manual into another language, under the above conditions for modified
15 versions, except that this permission notice may be included in
16 translations approved by the Free Software Foundation instead of in
17 the original English.
18 ..
19 .de TQ
20 .br
21 .ns
22 .TP \\$1
23 ..
24 .\" Like TP, but if specified indent is more than half
25 .\" the current line-length - indent, use the default indent.
26 .de Tp
27 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
28 .el .TP "\\$1"
29 ..
30 .TH GROFF_FONT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
31 .SH NAME
32 groff_font \- format of groff device and font description files
33 .SH DESCRIPTION
34 The groff font format is roughly a superset of the ditroff
35 font format.
36 Unlike the ditroff font format, there is no associated binary
37 format.
38 The font files for device
39 .I name
40 are stored in a directory
41 .BI dev name.
42 There are two types of file: a
43 device description file called
44 .B DESC
45 and for each font
46 .I F
47 a font file called
48 .IR F .
49 These are text files;
50 there is no associated binary format.
51 .SS DESC file format
52 The DESC file can contain the following types of line:
53 .TP
54 .BI res\ n
55 There are
56 .I n
57 machine units per inch.
58 .TP
59 .BI hor\ n
60 The horizontal resolution is
61 .I n
62 machine units.
63 .TP
64 .BI vert\ n
65 The vertical resolution is
66 .I n
67 machine units.
68 .TP
69 .BI sizescale\ n
70 The scale factor for pointsizes.
71 By default this has a value of 1.
72 One
73 .I
74 scaled point
75 is equal to
76 one
77 .RI point/ n .
78 The arguments to the
79 .B unitwidth
80 and
81 .B sizes
82 commands are given in scaled points.
83 .TP
84 .BI unitwidth\ n
85 Quantities in the font files are given in machine units
86 for fonts whose point size is
87 .I n
88 scaled points.
89 .TP
90 .B tcommand
91 This means that the postprocessor can handle the
92 .B t
93 and
94 .B u
95 output commands.
96 .TP
97 .BI sizes\ s1\ s2\|.\|.\|.\|sn\ 0
98 This means that the device has fonts at
99 .IR s1 ,
100 .IR s2 ,\|.\|.\|.\| sn
101 scaled points.
102 The list of sizes must be terminated by a
103 .BR 0 .
104 Each
105 .BI s i
106 can also be a range of sizes
107 .IR m \- n .
108 The list can extend over more than one line.
109 .TP
110 .BI styles\ S1\ S2\|.\|.\|.\|Sm
111 The first
112 .I m
113 font positions will be associated with styles
114 .IR S1\|.\|.\|.\|Sm .
115 .TP
116 .BI fonts\ n\ F1\ F2\ F3\|.\|.\|.\|Fn
117 Fonts
118 .I F1\|.\|.\|.\|Fn
119 will be mounted in the font positions
120 .IR m +1,\|.\|.\|., m + n
121 where
122 .I m
123 is the number of styles.
124 This command may extend over more than one line.
125 A font name of
126 .B 0
127 will cause no font to be mounted on the corresponding font position.
128 .TP
129 .BI family\ fam
130 The default font family is
131 .IR fam .
132 .TP
133 .B use_charnames_in_special
134 This command indicates that troff should encode named characters inside
135 special commands.
136 .TP
137 .B pass_filenames
138 requests that troff tells the driver the source file name being processed.
139 This is achieved by another tcommand:
140 .B F
141 .IR filename .
142 .TP
143 .B charset
144 This line and everything following in the file are ignored.
145 It is allowed for the sake of backwards compatibility.
146 .LP
147 The res, unitwidth, fonts and sizes lines are compulsory.
148 Other commands are ignored by
149 .B troff
150 but may be used by postprocessors to store arbitrary information
151 about the device in the DESC file.
152 .LP
153 Here a list of obsolete keywords which are recognized by
154 .B groff
155 but completely ignored:
156 .BR spare1 ,
157 .BR spare2 ,
158 .BR biggestfont .
159 .SS Font file format
160 A font file has two sections. The first section is a sequence
161 of lines each containing a sequence of blank delimited
162 words; the first word in the line is a key, and subsequent
163 words give a value for that key.
164 .TP
165 .BI name\ F
166 The name of the font is
167 .IR F .
168 .TP
169 .BI spacewidth\ n
170 The normal width of a space is
171 .IR n .
172 .TP
173 .BI slant\ n
174 The characters of the font have a slant of
175 .I n
176 degrees. (Positive means forward.)
177 .TP
178 .BI ligatures\ lig1\ lig2\|.\|.\|.\|lign\ \fR[ 0 \fR]
179 Characters
180 .IR lig1 ,
181 .IR lig2 ,\|.\|.\|., lign
182 are ligatures; possible ligatures are
183 .BR ff ,
184 .BR fi ,
185 .BR fl ,
186 .B ffi
187 and
188 .BR ffl .
189 For backwards compatibility, the list of ligatures may be terminated
190 with a
191 .BR 0.
192 The list of ligatures may not extend over more than one line.
193 .TP
194 .B special
195 The font is
196 .IR special ;
197 this means that when a character is requested that is not present in
198 the current font, it will be searched for in any special fonts that
199 are mounted.
200 .LP
201 Other commands are ignored by
202 .B troff
203 but may be used by postprocessors to store arbitrary information
204 about the font in the font file.
205 .LP
206 The first section can contain comments which start with the
207 .B #
208 character and extend to the end of a line.
209 .LP
210 The second section contains one or two subsections.
211 It must contain a
212 .I charset
213 subsection
214 and it may also contain a
215 .I kernpairs
216 subsection.
217 These subsections can appear in any order.
218 Each subsection starts with a word on a line by itself.
219 .LP
220 The word
221 .B charset
222 starts the charset subsection.
223 The
224 .B charset
225 line is followed by a sequence of lines.
226 Each line gives information for one character.
227 A line comprises a number of fields separated
228 by blanks or tabs. The format is
229 .IP
230 .I name metrics type code
231 .RI [ entity_name ]
232 .RB [ --
233 .IR comment ]
234 .LP
235 .I name
236 identifies the character:
237 if
238 .I name
239 is a single character
240 .I c
241 then it corresponds to the groff input character
242 .IR c ;
243 if it is of the form
244 .BI \e c
245 where c is a single character, then it
246 corresponds to the groff input character
247 .BI \e c\fR;
248 otherwise it corresponds to the groff input character
249 .BI \e[ name ]
250 (if it is exactly two characters
251 .I xx
252 it can be entered as
253 .BI \e( xx\fR.)
254 Groff supports eight bit characters; however some utilities
255 has difficulties with eight bit characters.
256 For this reason, there is a convention that the name
257 .BI char n
258 is equivalent to the single character whose code is
259 .I n .
260 For example,
261 .B char163
262 would be equivalent to the character with code 163
263 which is the pounds sterling sign in ISO Latin-1.
264 The name
265 .B \-\-\-
266 is special and indicates that the character is unnamed;
267 such characters can only be used by means of the
268 .B \eN
269 escape sequence in
270 .BR troff .
271 .LP
272 The
273 .I type
274 field gives the character type:
275 .TP
276 1
277 means the character has an descender, for example, p;
278 .TP
279 2
280 means the character has an ascender, for example, b;
281 .TP
282 3
283 means the character has both an ascender and a descender, for example,
284 (.
285 .LP
286 The
287 .I code
288 field gives the code which the postprocessor uses to print the character.
289 The character can also be input to groff using this code by means of the
290 .B \eN
291 escape sequence.
292 The code can be any integer.
293 If it starts with a
294 .B 0
295 it will be interpreted as octal;
296 if it starts with
297 .B 0x
298 or
299 .B 0X
300 it will be intepreted as hexadecimal.
301 .LP
302 The
303 .I entity_name
304 field gives an ascii string identifying the glyph which the postprocessor
305 uses to print the character.
306 This field is optional and has been introduced so that the html device driver
307 can encode its character set.
308 For example, the character `\e[Po]' is represented as `£' in html 4.0.
309 .LP
310 Anything on the line after the encoding field resp. after `-\&-' will
311 be ignored.
312 .LP
313 The
314 .I metrics
315 field has the form:
316 .IP
317 .IR width [\fB, height [\fB, depth [\fB, italic_correction [\fB, \
318 left_italic_correction [\fB, subscript_correction ]]]]]
319 .LP
320 There must not be any spaces between these subfields.
321 Missing subfields are assumed to be 0.
322 The subfields are all decimal integers.
323 Since there is no associated binary format, these
324 values are not required to fit into a variable of type
325 .B char
326 as they are in ditroff.
327 The
328 .I width
329 subfields gives the width of the character.
330 The
331 .I height
332 subfield gives the height of the character (upwards is positive);
333 if a character does not extend above the baseline, it should be
334 given a zero height, rather than a negative height.
335 The
336 .I depth
337 subfield gives the depth of the character, that is, the distance
338 below the lowest point below the baseline to which the
339 character extends (downwards is positive);
340 if a character does not extend below above the baseline, it should be
341 given a zero depth, rather than a negative depth.
342 The
343 .I italic_correction
344 subfield gives the amount of space that should be added after the
345 character when it is immediately to be followed by a character
346 from a roman font.
347 The
348 .I left_italic_correction
349 subfield gives the amount of space that should be added before the
350 character when it is immediately to be preceded by a character
351 from a roman font.
352 The
353 .I subscript_correction
354 gives the amount of space that should be added after a character
355 before adding a subscript.
356 This should be less than the italic correction.
357 .LP
358 A line in the charset section can also have the format
359 .IP
360 .I
361 name \fB"
362 .LP
363 This indicates that
364 .I name
365 is just another name for the character mentioned in the
366 preceding line.
367 .LP
368 The word
369 .B kernpairs
370 starts the kernpairs section.
371 This contains a sequence of lines of the form:
372 .IP
373 .I
374 c1 c2 n
375 .LP
376 This means that when character
377 .I c1
378 appears next to character
379 .I c2
380 the space between them should be increased by
381 .IR n .
382 Most entries in kernpairs section will have a negative value for
383 .IR n .
384 .SH FILES
385 .Tp \w'@FONTDIR@/devname/DESC'u+3n
386 .BI @FONTDIR@/dev name /DESC
387 Device description file for device
388 .IR name .
389 .TP
390 .BI @FONTDIR@/dev name / F
391 Font file for font
392 .I F
393 of device
394 .IR name .
395 .SH "SEE ALSO"
396 .BR groff_out (@MAN5EXT@),
397 .BR @g@troff (@MAN1EXT@).