| blob | e6ef8d38ceff394d1431b44592955dd439412aae |
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 .BI unitwidth\ n
291 Quantities in the font files are given in machine units
292 for fonts whose point size is
293 .I n
294 scaled points.
295 .
296 .TP
297 .B unscaled_charwidths
298 Make the font handling module always return unscaled character widths.
299 .
300 Needed for the
301 .B \%grohtml
302 device.
303 .
304 .TP
305 .B use_charnames_in_special
306 This command indicates that troff should encode named characters inside
307 special commands.
308 .
309 .TP
310 .BI vert\ n
311 The vertical resolution is
312 .I n
313 machine units.
314 .
315 .LP
316 The
317 .BR res ,
318 .BR unitwidth ,
319 .BR fonts ,
320 and
321 .B sizes
322 lines are compulsory.
323 .
324 Not all commands in the DESC file are used by
325 .B troff
326 itself; some of the keywords (or even additional ones) are used by
327 postprocessors to store arbitrary information about the device.
328 .
329 .LP
330 Here a list of obsolete keywords which are recognized by
331 .B groff
332 but completely ignored:
333 .BR spare1 ,
334 .BR spare2 ,
335 .BR biggestfont .
336 .
337 .
338 .SS Font file format
339 .
340 A font file has two sections;
341 empty lines are ignored in both of them.
342 .
343 .LP
344 The first section is a sequence
345 of lines each containing a sequence of blank delimited
346 words; the first word in the line is a key, and subsequent
347 words give a value for that key.
348 .
349 .TP
350 .BI ligatures\ lig1\ lig2\ \|.\|.\|.\|\ lign\ \fR[ 0 \fR]
351 Characters
352 .IR lig1 ,
353 .IR lig2 ,\ \|.\|.\|.,\ lign
354 are ligatures; possible ligatures are
355 .BR ff ,
356 .BR fi ,
357 .BR fl ,
358 .B ffi
359 and
360 .BR ffl .
361 .
362 For backwards compatibility, the list of ligatures may be terminated
363 with a
364 .BR 0.
365 .
366 The list of ligatures may not extend over more than one line.
367 .
368 .TP
369 .BI name\ F
370 The name of the font is
371 .IR F .
372 .
373 .TP
374 .BI slant\ n
375 The characters of the font have a slant of
376 .I n
377 degrees.
378 .
379 (Positive means forward.)
380 .
381 .TP
382 .BI spacewidth\ n
383 The normal width of a space is
384 .IR n .
385 .
386 .TP
387 .B special
388 The font is
389 .IR special ;
390 this means that when a character is requested that is not present in
391 the current font, it is searched for in any special fonts that are mounted.
392 .
393 .LP
394 Other commands are ignored by
395 .B troff
396 but may be used by postprocessors to store arbitrary information
397 about the font in the font file.
398 .
399 .LP
400 The first section can contain comments which start with the
401 .B #
402 character and extend to the end of a line.
403 .
404 .LP
405 The second section contains one or two subsections.
406 .
407 It must contain a
408 .I charset
409 subsection
410 and it may also contain a
411 .I kernpairs
412 subsection.
413 .
414 These subsections can appear in any order.
415 .
416 Each subsection starts with a word on a line by itself.
417 .
418 .LP
419 The word
420 .B charset
421 starts the charset subsection.
422 .
423 The
424 .B charset
425 line is followed by a sequence of lines.
426 .
427 Each line gives information for one character.
428 .
429 A line comprises a number of fields separated
430 by blanks or tabs.
431 .
432 The format is
433 .
434 .IP
435 .I name metrics type code
436 .RI [ entity_name ]
437 .RB [ --
438 .IR comment ]
439 .
440 .LP
441 .I name
442 identifies the character:
443 if
444 .I name
445 is a single character
446 .I c
447 then it corresponds to the groff input character
448 .IR c ;
449 if it is of the form
450 .BI \[rs] c
451 where c is a single character, then it
452 corresponds to the special character
453 .BI \[rs][ c ]\fR;
454 otherwise it corresponds to the groff input character
455 .BI \[rs][ name ]\fR.
456 .
457 If it is exactly two characters
458 .I xx
459 it can be entered as
460 .BI \[rs]( xx\fR.
461 .
462 Note that single-letter special characters can't be accessed as
463 .BI \[rs] c\fR;
464 the only exception is `\[rs]-' which is identical to `\[rs][-]'.
465 .
466 The name
467 .B \-\-\-
468 is special and indicates that the character is unnamed;
469 such characters can only be used by means of the
470 .B \[rs]N
471 escape sequence in
472 .BR troff .
473 .
474 .LP
475 Groff supports eight-bit characters; however some utilities
476 have difficulties with eight-bit characters.
477 .
478 For this reason, there is a convention that the name
479 .BI char n
480 is equivalent to the single character whose code is
481 .IR n .
482 .
483 For example,
484 .B char163
485 would be equivalent to the character with code 163
486 which is the pounds sterling sign in ISO Latin-1.
487 .
488 .LP
489 The
490 .I type
491 field gives the character type:
492 .
493 .TP
494 1
495 means the character has a descender, for example, p;
496 .
497 .TP
498 2
499 means the character has an ascender, for example, b;
500 .
501 .TP
502 3
503 means the character has both an ascender and a descender, for example,
504 (.
505 .
506 .LP
507 The
508 .I code
509 field gives the code which the postprocessor uses to print the character.
510 .
511 The character can also be input to groff using this code by means of the
512 .B \[rs]N
513 escape sequence.
514 .
515 The code can be any integer.
516 .
517 If it starts with a
518 .B 0
519 it is interpreted as octal;
520 if it starts with
521 .B 0x
522 or
523 .B 0X
524 it is intepreted as hexadecimal.
525 .
526 Note, however, that the
527 .B \[rs]N
528 escape sequence only accepts a decimal integer.
529 .
530 .LP
531 The
532 .I entity_name
533 field gives an ascii string identifying the glyph which the postprocessor
534 uses to print the character.
535 .
536 This field is optional and is currently used by
537 .B grops
538 to build sub-encoding arrays for PS fonts containing more than 256 glyphs.
539 .
540 (It has also been used for
541 .BR \%grohtml 's
542 entity names but for efficiency reasons this data is now compiled directly
543 into
544 .BR \%grohtml .)
545 .
546 .LP
547 Anything on the line after the encoding field or `-\&-' are ignored.
548 .
549 .LP
550 The
551 .I metrics
552 field has the form (in one line; it is broken here for the sake of
553 readability):
554 .
555 .IP
556 .I width\c
557 .RI [\fB, height\c
558 .RI [\fB, depth\c
559 .RI [\fB, italic-correction
560 .br
561 .RI [\fB, left-italic-correction\c
562 .RI [\fB, subscript-correction ]]]]]
563 .
564 .LP
565 There must not be any spaces between these subfields.
566 .
567 Missing subfields are assumed to be 0.
568 .
569 The subfields are all decimal integers.
570 .
571 Since there is no associated binary format, these
572 values are not required to fit into a variable of type
573 .B char
574 as they are in ditroff.
575 .
576 The
577 .I width
578 subfields gives the width of the character.
579 .
580 The
581 .I height
582 subfield gives the height of the character (upwards is positive);
583 if a character does not extend above the baseline, it should be
584 given a zero height, rather than a negative height.
585 .
586 The
587 .I depth
588 subfield gives the depth of the character, that is, the distance
589 below the lowest point below the baseline to which the
590 character extends (downwards is positive);
591 if a character does not extend below above the baseline, it should be
592 given a zero depth, rather than a negative depth.
593 .
594 The
595 .I italic-correction
596 subfield gives the amount of space that should be added after the
597 character when it is immediately to be followed by a character
598 from a roman font.
599 .
600 The
601 .I left-italic-correction
602 subfield gives the amount of space that should be added before the
603 character when it is immediately to be preceded by a character
604 from a roman font.
605 .
606 The
607 .I subscript-correction
608 gives the amount of space that should be added after a character
609 before adding a subscript.
610 .
611 This should be less than the italic correction.
612 .
613 .LP
614 A line in the charset section can also have the format
615 .
616 .IP
617 .I
618 name \fB"
619 .
620 .LP
621 This indicates that
622 .I name
623 is just another name for the character mentioned in the
624 preceding line.
625 .
626 .LP
627 The word
628 .B kernpairs
629 starts the kernpairs section.
630 .
631 This contains a sequence of lines of the form:
632 .
633 .IP
634 .I c1 c2 n
635 .
636 .LP
637 This means that when character
638 .I c1
639 appears next to character
640 .I c2
641 the space between them should be increased by
642 .IR n .
643 .
644 Most entries in kernpairs section have a negative value for
645 .IR n .
646 .
647 .
648 .SH FILES
649 .
650 .Tp \w'@FONTDIR@/devname/DESC'u+3n
651 .BI @FONTDIR@/dev name /DESC
652 Device description file for device
653 .IR name .
654 .
655 .TP
656 .BI @FONTDIR@/dev name / F
657 Font file for font
658 .I F
659 of device
660 .IR name .
661 .
662 .
663 .SH "SEE ALSO"
664 .
665 .BR groff_out (@MAN5EXT@),
666 .BR @g@troff (@MAN1EXT@).
667 .
668 .cp \n[groff_font_C]
669 .
670 .\" Local Variables:
671 .\" mode: nroff
672 .\" End: