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