* doc/fdl.texi: New file.
[s-roff.git] / man / groff_font.man
bloba7118f04362ce2fffc1e4c6399d7664ee0dc5b67
1 .ig
2 Copyright (C) 1989-1995, 2001, 2002 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.
19 .de TQ
20 .br
21 .ns
22 .TP \\$1
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"
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 The font files for device
37 .I name
38 are stored in a directory
39 .BI dev name.
40 There are two types of file: a
41 device description file called
42 .B DESC
43 and for each font
44 .I F
45 a font file called
46 .IR F .
47 These are text files;
48 unlike the ditroff font format,
49 there is no associated binary format.
50 .SS DESC file format
51 The DESC file can contain the following types of line:
52 .TP
53 .BI res\  n
54 There are
55 .I n
56 machine units per inch.
57 .TP
58 .BI hor\  n
59 The horizontal resolution is
60 .I n
61 machine units.
62 .TP
63 .BI vert\  n
64 The vertical resolution is
65 .I n
66 machine units.
67 .TP
68 .BI sizescale\  n
69 The scale factor for pointsizes.
70 By default this has a value of 1.
71 One
73 scaled point
74 is equal to
75 one
76 .RI point/ n .
77 The arguments to the
78 .B unitwidth
79 and
80 .B sizes
81 commands are given in scaled points.
82 .TP
83 .BI unitwidth\  n
84 Quantities in the font files are given in machine units
85 for fonts whose point size is
86 .I n 
87 scaled points.
88 .TP
89 .BI prepro\  program
90 Call
91 .I program
92 as a preprocessor.
93 .TP
94 .BI postpro\  program
95 Use
96 .I program
97 as the postprocessor.
98 .TP
99 .B tcommand
100 This means that the postprocessor can handle the
101 .B t
103 .B u
104 output commands.
106 .BI sizes\  s1\ s2\|.\|.\|.\|sn\  0
107 This means that the device has fonts at
108 .IR s1 ,
109 .IR s2 ,\|.\|.\|.\| sn
110 scaled points.
111 The list of sizes must be terminated by a
112 .BR 0 .
113 Each
114 .I si
115 can also be a range of sizes
116 .IR m \- n .
117 The list can extend over more than one line.
119 .BI styles\  S1\ S2\|.\|.\|.\|Sm
120 The first
121 .I m
122 font positions will be associated with styles
123 .IR S1\|.\|.\|.\|Sm .
125 .BI fonts\  n\ F1\ F2\ F3\|.\|.\|.\|Fn
126 Fonts
127 .I F1\|.\|.\|.\|Fn
128 will be mounted in the font positions 
129 .IR m +1,\|.\|.\|., m + n
130 where
131 .I m
132 is the number of styles.
133 This command may extend over more than one line.
134 A font name of
135 .B 0
136 will cause no font to be mounted on the corresponding font position.
138 .BI family\  fam
139 The default font family is
140 .IR fam .
142 .B use_charnames_in_special
143 This command indicates that troff should encode named characters inside
144 special commands.
146 .B pass_filenames
147 requests that troff tells the driver the source file name being processed.
148 This is achieved by another tcommand:
149 .B F
150 .IR filename .
152 .B charset
153 This line and everything following in the file are ignored.
154 It is allowed for the sake of backwards compatibility.
156 .BI print\  program
158 .I program
159 as the spooler program for printing.
160 If omitted, the
161 .B \-l
163 .B \-L
164 options of
165 .B groff
166 are ignored.
168 The res, unitwidth, fonts and sizes lines are compulsory.
169 Other commands are ignored by
170 .B troff
171 but may be used by postprocessors to store arbitrary information
172 about the device in the DESC file.
174 Here a list of obsolete keywords which are recognized by
175 .B groff
176 but completely ignored:
177 .BR spare1 ,
178 .BR spare2 ,
179 .BR biggestfont .
180 .SS Font file format
181 A font file has two sections. The first section is a sequence
182 of lines each containing a sequence of blank delimited
183 words; the first word in the line is a key, and subsequent
184 words give a value for that key.
186 .BI name\  F
187 The name of the font is
188 .IR F .
190 .BI spacewidth\  n
191 The normal width of a space is
192 .IR n .
194 .BI slant\  n
195 The characters of the font have a slant of
196 .I n
197 degrees. (Positive means forward.)
199 .BI ligatures\  lig1\ lig2\|.\|.\|.\|lign\ \fR[ 0 \fR]
200 Characters
201 .IR lig1 ,
202 .IR lig2 ,\|.\|.\|., lign
203 are ligatures; possible ligatures are
204 .BR ff ,
205 .BR fi ,
206 .BR fl ,
207 .B ffi
209 .BR ffl .
210 For backwards compatibility, the list of ligatures may be terminated
211 with a
212 .BR 0.
213 The list of ligatures may not extend over more than one line.
215 .B special
216 The font is
217 .IR special ;
218 this means that when a character is requested that is not present in
219 the current font, it will be searched for in any special fonts that
220 are mounted.
222 Other commands are ignored by
223 .B troff
224 but may be used by postprocessors to store arbitrary information
225 about the font in the font file.
227 The first section can contain comments which start with the
228 .B #
229 character and extend to the end of a line.
231 The second section contains one or two subsections.
232 It must contain a
233 .I charset
234 subsection
235 and it may also contain a
236 .I kernpairs
237 subsection.
238 These subsections can appear in any order.
239 Each subsection starts with a word on a line by itself.
241 The word
242 .B charset
243 starts the charset subsection.
245 .B charset
246 line is followed by a sequence of lines.
247 Each line gives information for one character.
248 A line comprises a number of fields separated
249 by blanks or tabs. The format is
251 .I name metrics type code 
252 .RI [ entity_name ]
253 .RB [ --
254 .IR comment ]
256 .I name
257 identifies the character:
259 .I name
260 is a single character
261 .I c
262 then it corresponds to the groff input character
263 .IR c ;
264 if it is of the form
265 .BI \[rs] c
266 where c is a single character, then it
267 corresponds to the special character
268 .BI \[rs][ c ]\fR;
269 otherwise it corresponds to the groff input character
270 .BI \[rs][ name ]\fR.
271 If it is exactly two characters
272 .I xx
273 it can be entered as
274 .BI \[rs]( xx\fR.
275 Note that single-letter special characters can't be accessed as
276 .BI \[rs] c\fR;
277 the only exception is `\[rs]-' which is identical to `\[rs][-]'.
279 Groff supports eight-bit characters; however some utilities
280 have difficulties with eight-bit characters.
281 For this reason, there is a convention that the name
282 .BI char n
283 is equivalent to the single character whose code is
284 .IR n .
285 For example,
286 .B char163
287 would be equivalent to the character with code 163
288 which is the pounds sterling sign in ISO Latin-1.
289 The name
290 .B \-\-\-
291 is special and indicates that the character is unnamed;
292 such characters can only be used by means of the
293 .B \[rs]N
294 escape sequence in
295 .BR troff .
298 .I type
299 field gives the character type:
302 means the character has a descender, for example, p;
305 means the character has an ascender, for example, b;
308 means the character has both an ascender and a descender, for example,
312 .I code
313 field gives the code which the postprocessor uses to print the character.
314 The character can also be input to groff using this code by means of the
315 .B \[rs]N
316 escape sequence.
317 The code can be any integer.
318 If it starts with a
319 .B 0
320 it will be interpreted as octal;
321 if it starts with
322 .B 0x
324 .B 0X
325 it will be intepreted as hexadecimal.
328 .I entity_name
329 field gives an ascii string identifying the glyph which the postprocessor
330 uses to print the character.
331 This field is optional and has been introduced so that the html device driver
332 can encode its character set.
333 For example, the character `\[rs][Po]' is represented as `£' in
334 html\~4.0.
336 Anything on the line after the encoding field resp. after `-\&-' will
337 be ignored.
340 .I metrics
341 field has the form:
343 .IR width [\fB, height [\fB, depth [\fB, italic_correction [\fB, \
344 left_italic_correction [\fB, subscript_correction ]]]]]
346 There must not be any spaces between these subfields.
347 Missing subfields are assumed to be 0.
348 The subfields are all decimal integers.
349 Since there is no associated binary format, these
350 values are not required to fit into a variable of type
351 .B char
352 as they are in ditroff.
354 .I width
355 subfields gives the width of the character.
357 .I height
358 subfield gives the height of the character (upwards is positive);
359 if a character does not extend above the baseline, it should be
360 given a zero height, rather than a negative height.
362 .I depth
363 subfield gives the depth of the character, that is, the distance
364 below the lowest point below the baseline to which the
365 character extends (downwards is positive);
366 if a character does not extend below above the baseline, it should be
367 given a zero depth, rather than a negative depth.
369 .I italic_correction
370 subfield gives the amount of space that should be added after the
371 character when it is immediately to be followed by a character
372 from a roman font.
374 .I left_italic_correction
375 subfield gives the amount of space that should be added before the
376 character when it is immediately to be preceded by a character
377 from a roman font.
379 .I subscript_correction
380 gives the amount of space that should be added after a character
381 before adding a subscript.
382 This should be less than the italic correction.
384 A line in the charset section can also have the format
387 name \fB"
389 This indicates that
390 .I name
391 is just another name for the character mentioned in the
392 preceding line.
394 The word
395 .B kernpairs
396 starts the kernpairs section.
397 This contains a sequence of lines of the form:
400 c1 c2 n
402 This means that when character
403 .I c1
404 appears next to character
405 .I c2
406 the space between them should be increased by
407 .IR n .
408 Most entries in kernpairs section will have a negative value for
409 .IR n .
410 .SH FILES
411 .Tp \w'@FONTDIR@/devname/DESC'u+3n
412 .BI @FONTDIR@/dev name /DESC
413 Device description file for device
414 .IR name .
416 .BI @FONTDIR@/dev name / F
417 Font file for font
418 .I F
419 of device
420 .IR name .
421 .SH "SEE ALSO"
422 .BR groff_out (@MAN5EXT@),
423 .BR @g@troff (@MAN1EXT@).
425 .\" Local Variables:
426 .\" mode: nroff
427 .\" End: