| blob | 2b9316a75e748ee53dc8b5fcc44e99012bf868c8 |
1 .ig
2 Copyright (C) 1989-1995, 2001, 2002, 2003 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 .
20 .do nr groff_font_C \n[.C]
21 .cp 0
22 .
23 .de TQ
24 . br
25 . ns
26 . TP \\$1
27 ..
28 .
29 .\" Like TP, but if specified indent is more than half
30 .\" the current line-length - indent, use the default indent.
31 .de Tp
32 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
33 . el .TP "\\$1"
34 ..
35 .
36 .
37 .TH GROFF_FONT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
38 .
39 .
40 .SH NAME
41 groff_font \- format of groff device and font description files
42 .
43 .
44 .SH DESCRIPTION
45 The groff font format is roughly a superset of the ditroff
46 font format.
47 .
48 The font files for device
49 .I name
50 are stored in a directory
51 .BI dev name.
52 .
53 There are two types of file: a
54 device description file called
55 .B DESC
56 and for each font
57 .I F
58 a font file called
59 .IR F .
60 .
61 These are text files;
62 unlike the ditroff font format,
63 there is no associated binary format.
64 .
65 .
66 .SS DESC file format
67 .
68 The DESC file can contain the following types of line as shown below.
69 .
70 Later entries in the file override previous values.
71 .
72 .TP
73 .B charset
74 This line and everything following in the file are ignored.
75 .
76 It is allowed for the sake of backwards compatibility.
77 .
78 .TP
79 .BI family\ fam
80 The default font family is
81 .IR fam .
82 .
83 .TP
84 .BI fonts\ n\ F1\ F2\ F3\|.\|.\|.\|Fn
85 Fonts
86 .I F1\|.\|.\|.\|Fn
87 will be mounted in the font positions
88 .IR m +1,\|.\|.\|., m + n
89 where
90 .I m
91 is the number of styles.
92 .
93 This command may extend over more than one line.
94 .
95 A font name of
96 .B 0
97 will cause no font to be mounted on the corresponding font position.
98 .
99 .TP
100 .BI hor\ n
101 The horizontal resolution is
102 .I n
103 machine units.
104 .
105 .TP
106 .BI paperheight\ n
107 The physical vertical dimension of the output medium in machine units.
108 .
109 This isn't used by
110 .B troff
111 itself but by output devices.
112 .
113 Deprecated.
114 .
115 Use
116 .B papersize
117 instead.
118 .
119 .TP
120 .BI papersize\ string
121 Select a paper size.
122 .
123 Valid values for
124 .I string
125 are the ISO paper types A0-A7, B0-B7, C0-C7, D0-D7, DL, and the US paper
126 types letter, legal, tabloid, ledger, statement, executive, com10, and
127 monarch.
128 .
129 Case is not significant for
130 .IR string
131 if it holds predefined paper types.
132 .
133 Alternatively,
134 .I string
135 can be a file name (e.g.\& `/etc/papersize'); if the file can be opened,
136 .B groff
137 reads the first line and tests for the above paper sizes.
138 .
139 Finally,
140 .I string
141 can be a custom paper size in the format
142 .IB length , width
143 (no spaces before and after the comma).
144 .
145 Both
146 .I length
147 and
148 .I width
149 must have a unit appended; valid values are `i' for inches, `c' for
150 centimeters, `p' for points, and `P' for picas.
151 .
152 Example:
153 .BR 12c,235p .
154 .
155 An argument which starts with a digit is always treated as a custom paper
156 format.
157 .
158 .B papersize
159 sets both the vertical and horizontal dimension of the output medium.
160 .
161 .IP
162 More than one argument can be specified;
163 .B groff
164 scans from left to right and uses the first valid paper specification.
165 .
166 .TP
167 .BI paperwidth\ n
168 The physical horizontal dimension of the output medium in machine units.
169 .
170 Deprecated.
171 .
172 Use
173 .B papersize
174 instead.
175 .
176 This isn't used by
177 .BR troff
178 itself but by output devices.
179 .
180 .TP
181 .B pass_filenames
182 Make troff tell the driver the source file name being processed.
183 .
184 This is achieved by another tcommand:
185 .B F
186 .IR filename .
187 .
188 .TP
189 .BI postpro\ program
190 Use
191 .I program
192 as the postprocessor.
193 .
194 .TP
195 .BI prepro\ program
196 Call
197 .I program
198 as a preprocessor.
199 .
200 .TP
201 .BI print\ program
202 Use
203 .I program
204 as the spooler program for printing.
205 .
206 If omitted, the
207 .B \-l
208 and
209 .B \-L
210 options of
211 .B groff
212 are ignored.
213 .
214 .TP
215 .BI res\ n
216 There are
217 .I n
218 machine units per inch.
219 .
220 .TP
221 .BI sizes\ s1\ s2\|.\|.\|.\|sn\ 0
222 This means that the device has fonts at
223 .IR s1 ,
224 .IR s2 ,\|.\|.\|.\| sn
225 scaled points.
226 .
227 The list of sizes must be terminated by a
228 .BR 0 .
229 .
230 Each
231 .I si
232 can also be a range of sizes
233 .IR m \- n .
234 .
235 The list can extend over more than one line.
236 .
237 .TP
238 .BI sizescale\ n
239 The scale factor for pointsizes.
240 .
241 By default this has a value of 1.
242 .
243 One
244 .I
245 scaled point
246 is equal to
247 one
248 .RI point/ n .
249 .
250 The arguments to the
251 .B unitwidth
252 and
253 .B sizes
254 commands are given in scaled points.
255 .
256 .TP
257 .BI styles\ S1\ S2\|.\|.\|.\|Sm
258 The first
259 .I m
260 font positions will be associated with styles
261 .IR S1\|.\|.\|.\|Sm .
262 .
263 .TP
264 .B tcommand
265 This means that the postprocessor can handle the
266 .B t
267 and
268 .B u
269 output commands.
270 .
271 .TP
272 .BI unitwidth\ n
273 Quantities in the font files are given in machine units
274 for fonts whose point size is
275 .I n
276 scaled points.
277 .
278 .TP
279 .B use_charnames_in_special
280 This command indicates that troff should encode named characters inside
281 special commands.
282 .
283 .TP
284 .BI vert\ n
285 The vertical resolution is
286 .I n
287 machine units.
288 .
289 .LP
290 The
291 .BR res ,
292 .BR unitwidth ,
293 .BR fonts ,
294 and
295 .B sizes
296 lines are compulsory.
297 .
298 Not all commands in the DESC file are used by
299 .B troff
300 itself; some of the keywords (or even additional ones) are used by
301 postprocessors to store arbitrary information about the device.
302 .
303 .LP
304 Here a list of obsolete keywords which are recognized by
305 .B groff
306 but completely ignored:
307 .BR spare1 ,
308 .BR spare2 ,
309 .BR biggestfont .
310 .
311 .
312 .SS Font file format
313 .
314 A font file has two sections.
315 The first section is a sequence
316 of lines each containing a sequence of blank delimited
317 words; the first word in the line is a key, and subsequent
318 words give a value for that key.
319 .
320 .TP
321 .BI ligatures\ lig1\ lig2\|.\|.\|.\|lign\ \fR[ 0 \fR]
322 Characters
323 .IR lig1 ,
324 .IR lig2 ,\ \|.\|.\|.,\ lign
325 are ligatures; possible ligatures are
326 .BR ff ,
327 .BR fi ,
328 .BR fl ,
329 .B ffi
330 and
331 .BR ffl .
332 .
333 For backwards compatibility, the list of ligatures may be terminated
334 with a
335 .BR 0.
336 .
337 The list of ligatures may not extend over more than one line.
338 .
339 .TP
340 .BI name\ F
341 The name of the font is
342 .IR F .
343 .
344 .TP
345 .BI slant\ n
346 The characters of the font have a slant of
347 .I n
348 degrees.
349 .
350 (Positive means forward.)
351 .
352 .TP
353 .BI spacewidth\ n
354 The normal width of a space is
355 .IR n .
356 .
357 .TP
358 .B special
359 The font is
360 .IR special ;
361 this means that when a character is requested that is not present in
362 the current font, it will be searched for in any special fonts that
363 are mounted.
364 .
365 .LP
366 Other commands are ignored by
367 .B troff
368 but may be used by postprocessors to store arbitrary information
369 about the font in the font file.
370 .
371 .LP
372 The first section can contain comments which start with the
373 .B #
374 character and extend to the end of a line.
375 .
376 .LP
377 The second section contains one or two subsections.
378 .
379 It must contain a
380 .I charset
381 subsection
382 and it may also contain a
383 .I kernpairs
384 subsection.
385 .
386 These subsections can appear in any order.
387 .
388 Each subsection starts with a word on a line by itself.
389 .
390 .LP
391 The word
392 .B charset
393 starts the charset subsection.
394 .
395 The
396 .B charset
397 line is followed by a sequence of lines.
398 .
399 Each line gives information for one character.
400 .
401 A line comprises a number of fields separated
402 by blanks or tabs.
403 .
404 The format is
405 .
406 .IP
407 .I name metrics type code
408 .RI [ entity_name ]
409 .RB [ --
410 .IR comment ]
411 .
412 .LP
413 .I name
414 identifies the character:
415 if
416 .I name
417 is a single character
418 .I c
419 then it corresponds to the groff input character
420 .IR c ;
421 if it is of the form
422 .BI \[rs] c
423 where c is a single character, then it
424 corresponds to the special character
425 .BI \[rs][ c ]\fR;
426 otherwise it corresponds to the groff input character
427 .BI \[rs][ name ]\fR.
428 .
429 If it is exactly two characters
430 .I xx
431 it can be entered as
432 .BI \[rs]( xx\fR.
433 .
434 Note that single-letter special characters can't be accessed as
435 .BI \[rs] c\fR;
436 the only exception is `\[rs]-' which is identical to `\[rs][-]'.
437 .
438 The name
439 .B \-\-\-
440 is special and indicates that the character is unnamed;
441 such characters can only be used by means of the
442 .B \[rs]N
443 escape sequence in
444 .BR troff .
445 .
446 .LP
447 Groff supports eight-bit characters; however some utilities
448 have difficulties with eight-bit characters.
449 .
450 For this reason, there is a convention that the name
451 .BI char n
452 is equivalent to the single character whose code is
453 .IR n .
454 .
455 For example,
456 .B char163
457 would be equivalent to the character with code 163
458 which is the pounds sterling sign in ISO Latin-1.
459 .
460 .LP
461 The
462 .I type
463 field gives the character type:
464 .
465 .TP
466 1
467 means the character has a descender, for example, p;
468 .
469 .TP
470 2
471 means the character has an ascender, for example, b;
472 .
473 .TP
474 3
475 means the character has both an ascender and a descender, for example,
476 (.
477 .
478 .LP
479 The
480 .I code
481 field gives the code which the postprocessor uses to print the character.
482 .
483 The character can also be input to groff using this code by means of the
484 .B \[rs]N
485 escape sequence.
486 .
487 The code can be any integer.
488 .
489 If it starts with a
490 .B 0
491 it will be interpreted as octal;
492 if it starts with
493 .B 0x
494 or
495 .B 0X
496 it will be intepreted as hexadecimal.
497 .
498 Note, however, that the
499 .B \[rs]N
500 escape sequence only accepts a decimal integer.
501 .
502 .LP
503 The
504 .I entity_name
505 field gives an ascii string identifying the glyph which the postprocessor
506 uses to print the character.
507 .
508 This field is optional and has been introduced so that the html device driver
509 can encode its character set.
510 .
511 For example, the character `\[rs][Po]' is represented as `£' in
512 html\~4.0.
513 .
514 .LP
515 Anything on the line after the encoding field resp. after `-\&-' will
516 be ignored.
517 .
518 .LP
519 The
520 .I metrics
521 field has the form (in one line; it is broken here for the sake of
522 readability):
523 .
524 .IP
525 .IR width [\fB, height [\fB, depth [\fB, italic-correction
526 .br
527 .RI [\fB, left-italic-correction [\fB, subscript-correction ]]]]]
528 .
529 .LP
530 There must not be any spaces between these subfields.
531 .
532 Missing subfields are assumed to be 0.
533 .
534 The subfields are all decimal integers.
535 .
536 Since there is no associated binary format, these
537 values are not required to fit into a variable of type
538 .B char
539 as they are in ditroff.
540 .
541 The
542 .I width
543 subfields gives the width of the character.
544 .
545 The
546 .I height
547 subfield gives the height of the character (upwards is positive);
548 if a character does not extend above the baseline, it should be
549 given a zero height, rather than a negative height.
550 .
551 The
552 .I depth
553 subfield gives the depth of the character, that is, the distance
554 below the lowest point below the baseline to which the
555 character extends (downwards is positive);
556 if a character does not extend below above the baseline, it should be
557 given a zero depth, rather than a negative depth.
558 .
559 The
560 .I italic-correction
561 subfield gives the amount of space that should be added after the
562 character when it is immediately to be followed by a character
563 from a roman font.
564 .
565 The
566 .I left-italic-correction
567 subfield gives the amount of space that should be added before the
568 character when it is immediately to be preceded by a character
569 from a roman font.
570 .
571 The
572 .I subscript-correction
573 gives the amount of space that should be added after a character
574 before adding a subscript.
575 .
576 This should be less than the italic correction.
577 .
578 .LP
579 A line in the charset section can also have the format
580 .
581 .IP
582 .I
583 name \fB"
584 .
585 .LP
586 This indicates that
587 .I name
588 is just another name for the character mentioned in the
589 preceding line.
590 .
591 .LP
592 The word
593 .B kernpairs
594 starts the kernpairs section.
595 .
596 This contains a sequence of lines of the form:
597 .
598 .IP
599 .I c1 c2 n
600 .
601 .LP
602 This means that when character
603 .I c1
604 appears next to character
605 .I c2
606 the space between them should be increased by
607 .IR n .
608 .
609 Most entries in kernpairs section will have a negative value for
610 .IR n .
611 .
612 .
613 .SH FILES
614 .
615 .Tp \w'@FONTDIR@/devname/DESC'u+3n
616 .BI @FONTDIR@/dev name /DESC
617 Device description file for device
618 .IR name .
619 .
620 .TP
621 .BI @FONTDIR@/dev name / F
622 Font file for font
623 .I F
624 of device
625 .IR name .
626 .
627 .
628 .SH "SEE ALSO"
629 .
630 .BR groff_out (@MAN5EXT@),
631 .BR @g@troff (@MAN1EXT@).
632 .
633 .cp \n[groff_font_C]
634 .
635 .\" Local Variables:
636 .\" mode: nroff
637 .\" End: