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
21 .do nr groff_font_C \n[.C]
25 .\" Like TP, but if specified indent is more than half
26 .\" the current line-length - indent, use the default indent.
28 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
33 .TH GROFF_FONT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
37 groff_font \- format of groff device and font description files
41 The groff font format is roughly a superset of the ditroff
44 The font files for device
46 are stored in a directory
50 There are two types of file: a
51 device description file called
55 a font file called\~\c
59 unlike the ditroff font format,
60 there is no associated binary format.
65 The DESC file can contain the following types of line as shown below.
67 Later entries in the file override previous values.
70 Empty lines are ignored.
74 This line and everything following in the file are ignored.
76 It is allowed for the sake of backwards compatibility.
80 The default font family is
84 .BI fonts\ n\ F1\ F2\ F3\ \|.\|.\|.\|\ Fn
86 .IR F1 ,\ \|.\|.\|.,\ Fn
87 are mounted in the font positions
88 .IR m \|+\|1,\ \|.\|.\|.,\ m \|+\| n
91 is the number of styles.
93 This command may extend over more than one line.
97 causes no font to be mounted on the corresponding font position.
101 The horizontal resolution is
106 .BI image_generator\ string
111 It specifies the program to generate PNG images from
114 Under GNU/Linux this is usually
116 but under other systems (notably cygwin) it might be set to another name.
120 The physical vertical dimension of the output medium in machine units.
124 itself but by output devices.
133 .BI papersize\ 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
142 Case is not significant for
144 if it holds predefined paper types.
148 can be a file name (e.g.\& `/etc/papersize'); if the file can be opened,
150 reads the first line and tests for the above paper sizes.
154 can be a custom paper size in the format
156 (no spaces before and after the comma).
162 must have a unit appended; valid values are `i' for inches, `c' for
163 centimeters, `p' for points, and `P' for picas.
168 An argument which starts with a digit is always treated as a custom paper
172 sets both the vertical and horizontal dimension of the output medium.
175 More than one argument can be specified;
177 scans from left to right and uses the first valid paper specification.
181 The physical horizontal dimension of the output medium in machine units.
191 itself but by output devices.
195 Make troff tell the driver the source file name being processed.
197 This is achieved by another tcommand:
205 as the postprocessor.
217 as the spooler program for printing.
231 machine units per inch.
234 .BI sizes\ s1\ s2\ \|.\|.\|.\|\ sn\ 0
235 This means that the device has fonts at
237 .IR s2 ,\ \|.\|.\|.,\ sn
240 The list of sizes must be terminated by a
245 can also be a range of sizes
248 The list can extend over more than one line.
252 The scale factor for point sizes.
254 By default this has a value of 1.
267 commands are given in scaled points.
270 .BI styles\ S1\ S2\ \|.\|.\|.\|\ Sm
273 font positions are associated with styles
274 .IR S1 ,\ \|.\|.\|.,\ Sm .
278 This means that the postprocessor can handle the
286 Indicate that the output device supports the complete Unicode
289 Useful only for devices which produce
290 .I character entities
298 section is required in the font description files since the Unicode
303 However, if there are entries in a
305 section, they either override the default mappings for those
306 particular characters or add new mappings (normally for composite
318 Quantities in the font files are given in machine units
319 for fonts whose point size is
324 .B unscaled_charwidths
325 Make the font handling module always return unscaled glyph widths.
332 .B use_charnames_in_special
333 This command indicates that troff should encode named glyphs inside
338 The vertical resolution is
349 lines are compulsory.
351 Not all commands in the DESC file are used by
353 itself; some of the keywords (or even additional ones) are used by
354 postprocessors to store arbitrary information about the device.
357 Here a list of obsolete keywords which are recognized by
359 but completely ignored:
367 A font file has two sections;
368 empty lines are ignored in both of them.
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.
377 .BI ligatures\ lig1\ lig2\ \|.\|.\|.\|\ lign\ \fR[ 0 \fR]
380 .IR lig2 ,\ \|.\|.\|.,\ lign
381 are ligatures; possible ligatures are
389 For backwards compatibility, the list of ligatures may be terminated
393 The list of ligatures may not extend over more than one line.
397 The name of the font is\~\c
402 The glyphs of the font have a slant of
406 (Positive means forward.)
410 The normal width of a space is\~\c
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
422 Other commands are ignored by
424 but may be used by postprocessors to store arbitrary information
425 about the font in the font file.
428 The first section can contain comments which start with the
430 character and extend to the end of a line.
433 The second section contains one or two subsections.
438 and it may also contain a
442 These subsections can appear in any order.
444 Each subsection starts with a word on a line by itself.
449 starts the charset subsection.
453 line is followed by a sequence of lines.
455 Each line gives information for one glyph.
457 A line comprises a number of fields separated
463 .I name metrics type code
470 identifies the glyph:
475 then it corresponds to the groff input character
479 where c is a single character, then it
480 corresponds to the special character
482 otherwise it corresponds to the groff input character
483 .BI \[rs][ name ]\fR.
485 If it is exactly two characters
490 Note that single-letter special characters can't be accessed as
492 the only exception is `\[rs]\-' which is identical to `\[rs][\-]'.
496 is special and indicates that the glyph is unnamed;
497 such glyphs can only be used by means of the
505 field gives the glyph type:
509 means the glyph has a descender, for example, `p';
513 means the glyph has an ascender, for example, `b';
517 means the glyph has both an ascender and a descender, for example,
523 field gives the code which the postprocessor uses to print the glyph.
525 The glyph can also be input to groff using this code by means of the
529 The code can be any integer.
531 If it starts with a\~\c
533 it is interpreted as octal;
538 it is intepreted as hexadecimal.
540 Note, however, that the
542 escape sequence only accepts a decimal integer.
547 field gives an ASCII string identifying the glyph which the postprocessor
548 uses to print that glyph.
550 This field is optional and is currently used by
552 to build sub-encoding arrays for PS fonts containing more than 256 glyphs.
554 (It has also been used for
556 entity names but for efficiency reasons this data is now compiled directly
561 Anything on the line after the encoding field or `\-\-' are ignored.
566 field has the form (in one line; it is broken here for the sake of
573 .RI [\fB, italic-correction
575 .RI [\fB, left-italic-correction\c
576 .RI [\fB, subscript-correction ]]]]]
579 There must not be any spaces between these subfields.
581 Missing subfields are assumed to be\~0.
583 The subfields are all decimal integers.
585 Since there is no associated binary format, these
586 values are not required to fit into a variable of type
588 as they are in ditroff.
592 subfields gives the width of the glyph.
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.
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.
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
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
621 .I subscript-correction
622 gives the amount of space that should be added after a glyph
623 before adding a subscript.
625 This should be less than the italic correction.
628 A line in the charset section can also have the format
637 is just another name for the glyph mentioned in the
643 starts the kernpairs section.
645 This contains a sequence of lines of the form:
651 This means that when glyph
653 appears next to glyph
655 the space between them should be increased by\~\c
658 Most entries in kernpairs section have a negative value for\~\c
664 .Tp \w'@FONTDIR@/devname/DESC'u+3n
665 .BI @FONTDIR@/dev name /DESC
666 Device description file for device
670 .BI @FONTDIR@/dev name / F
671 Font file for font\~\c
679 .BR groff_out (@MAN5EXT@),
680 .BR @g@troff (@MAN1EXT@).