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