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