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