# Font utilities

The Web2c programs described here convert between various TeX-related font formats; the first section below briefly describes the formats. GFtoPK is the only one that is routinely used, as Metafont outputs GF format, but it's most efficient for device drivers to use PK.

The precise definitions of the PK, GF, TFM, PL, VF, and VPL formats mentioned below are in the source files that read them; `pktype.web', `gftype.web', `tftopl.web', etc.

## Font file formats

(For another perspective on this, see section `Font concepts' in Dvips).

Font files come in several varieties, with suffixes like:

.tfm  .*pk  .*gf  .*pxl (obsolete)  .pl  .mf  .vf  .vpl

Each represents a file format.

A TFM (TeX font metric) file is a compact binary file that contains information about each character in a font, about combinations of characters within that font, and about the font as a whole. The font metric information contained in TFM files is device-independent units is used by TeX to do typesetting. Unlike the bitmap (raster) fonts described below, TFM font files contain no information about the shapes of characters. They describe rectangular areas and combinations thereof, but not what will eventually be printed in those areas.

Since TeX does scaling calculations, one TFM file serves for all magnifications of a given typeface. On the other hand, the best printed results are obtained when magnified (or reduced fonts) are not produced geometrically (as done by PostScript, for example) but rather optically, with each size a separate design (as done with Computer Modern and the EC fonts, for example); then a separate TFM file is needed for each size.

At any rate, TeX produces a DVI (DeVice Independent) file from your source document. In order to print DVI files on real devices, you need font files defining digitized character shapes and other data. Then previewers and printer-driver programs can translate your DVI files into something usable by your monitor or printer. Bitmap fonts come with suffixes such as `.600pk' or `.600gf' or `.3000pxl', where the `600' is the horizontal dots-per-inch resolution at which the font was produced, and the `pk' or `gf' or `pxl' indicates the font format. Outline fonts in PostScript Type 1 format have suffixes such as `.pfa' or `.pfb'.

Fonts in pk (packed) format are in the tightly packed raster format that is pretty much the standard today. They take up less space than fonts in the gf (generic font) format that Metafont generates, and far less space than fonts in pxl format. Fonts in pxl format take up gross amounts of disk space and permit only 128 characters. They are obsolete.

Font files with the `.pl' (property list) suffix are the plain text (human-readable) analog of the binary `.tfm' files. The TFtoPL and PLtoTF programs convert between the two formats (see section TFtoPL: TeX font metric to property list conversion and section PLtoTF: Property list to TeX font metric conversion).

Font files with the `.mf' suffix are in Metafont source format. These are the files used by Metafont to generate rastered fonts for specific typefaces at specific magnifications for the specific resolution and type of mapping used by your device.

The suffix `.vf' identifies "virtual font" files, for which `.vpl' is the human-readable analog. See section VFtoVP: Virtual font to virtual property lists and section VPtoVF: Virtual property lists to virtual font. For further discussion of virtual fonts, see `CTAN:/doc/virtual-fonts.knuth', `CTAN:/help/virtualfonts.txt', and section `Virtual fonts' in Dvips.

(This section is based on documentation in the original Unix TeX distribution by Pierre MacKay and Elizabeth Tachikawa.)

## GFtoPK: Generic to packed font conversion

GFtoPK converts a generic font (GF) file output by, for example, Metafont (see section mf invocation) to a packed font (PK) file. PK files are considerably smaller than the corresponding gf files, so they are generally the bitmap font format of choice. Some DVI-processing programs, notably Dvips, only support PK files and not GF files. Synopsis:

gftopk [option]... gfname.dpi[gf] [pkfile]

The font gfname is searched for in the usual places (see section `Glyph lookup' in Kpathsea). To see all the relevant paths, set the environment variable KPATHSEA_DEBUG to `-1' before running the program.

The suffix `gf' is supplied if not already present. This suffix is not an extension; no `.' precedes it: for instance, `cmr10.600gf'.

If pkfile is not specified, the output is written to the basename of `gfname.dpipk', e.g., `gftopk /wherever/cmr10.600gf' creates `./cmr10.600pk'.

The only options are `--verbose', `--help', and `--version' (see section Common options).

## PKtoGF: Packed to generic font conversion

PKtoGF converts a packed font (PK) file to a generic font (GF) file. Since PK format is much more compact than GF format, the most likely reason to do this is to run GFtype (see section GFtype: Plain text transliteration of generic fonts) on the result, so you can see the bitmap images. Also, a few old utility programs do not support PK format. Synopsis:

pktogf [option]... pkname.dpi[pk] [gffile]

The font pkname is searched for in the usual places (see section `Glyph lookup' in Kpathsea). To see all the relevant paths, set the environment variable KPATHSEA_DEBUG to `-1' before running the program.

The suffix `pk' is supplied if not already present. This suffix is not an extension; no `.' precedes it: for instance, `cmr10.600pk'.

If gffile is not specified, the output is written to the basename of `pkname.dpigf', e.g., `pktogf /wherever/cmr10.600pk' creates `./cmr10.600gf'.

The only options are `--verbose', `--help', and `--version' (see section Common options).

## PKtype: Plain text transliteration of packed fonts

PKtype translates a packed font (PK) bitmap file (as output by GFtoPK, for example) to a plain text file that humans can read. It also serves as a PK-validating program, i.e., if PKtype can read a file, it's correct. Synopsis:

pktype pkname.dpi[pk]

The font pkname is searched for in the usual places (see section `Glyph lookup' in Kpathsea). To see all the relevant paths, set the environment variable KPATHSEA_DEBUG to `-1' before running the program.

The suffix `pk' is supplied if not already present. This suffix is not an extension; no `.' precedes it: for instance, `cmr10.600pk'.

The translation is written to standard output.

The only options are `-help' and `-version' (see section Common options).

As an example of the output, here is the (abridged) translation of the letter `K' in `cmr10', as rendered at 600dpi with the mode `ljfour' from modes.mf (available from `ftp://ftp.tug.org/tex/modes.mf').

955:  Flag byte = 184  Character = 75  Packet length = 174
Dynamic packing variable = 11
TFM width = 815562  dx = 4259840
Height = 57  Width = 57  X-offset = -3  Y-offset = 56
[2]23(16)17(8)9(25)11(13)7(27)7(16)7(28)4(18)7(28)2(20)7(27)...
...
(14)9(24)12(5)[2]23(13)21

Explanation:

`955'
The byte position in the file where this character starts.
`Flag byte'
`Dynamic packing variable'
Related to the packing for this character; see the source code.
`Character'
The character code, in decimal.
`Packet length'
The total length of this character definition, in bytes.
`TFM width'
The device-independent (TFM) width of this character. It is 2^24 times the ratio of the true width to the font's design size.
`dx'
The device-dependent width, in scaled pixels, i.e., units of horizontal pixels times 2^16.
`Height'
`Width'
The bitmap height and width, in pixels.
`X-offset'
`Y-offset'
Horizontal and vertical offset from the upper left pixel to the reference (origin) pixel for this character, in pixels (right and down are positive). The reference pixel is the pixel that occupies the unit square in Metafont; the Metafont reference point is the lower left hand corner of this pixel. Put another way, the x-offset is the negative of the left side bearing; the right side bearing is the horizontal escapement minus the bitmap width plus the x-offset.
`[2]23(16)...'
Finally, run lengths of black pixels alternate with parenthesized run lengths of white pixels, and brackets indicate a repeated row.

## GFtype: Plain text transliteration of generic fonts

GFtype translates a generic font (GF) bitmap file (as output by Metafont, for example) to a plain text file that humans can read. It also serves as a GF-validating program, i.e., if GFtype can read a file, it's correct. Synopsis:

gftype [option]... gfname.dpi[gf]

The font gfname is searched for in the usual places (see section `Glyph lookup' in Kpathsea). To see all the relevant paths, set the environment variable KPATHSEA_DEBUG to `-1' before running the program.

The suffix `gf' is supplied if not already present. This suffix is not an extension; no `.' precedes it: for instance, `cmr10.600gf'.

The translation is written to standard output.

The program accepts the following options, as well as the standard `-help' and `-version' (see section Common options):

`-images'
Show the characters' bitmaps using asterisks and spaces.
`-mnemonics'
Translate all commands in the GF file.

As an example of the output, here is the (abrdiged) translation of the letter `K' in `cmr10', as rendered at 600dpi with the mode `ljfour' from `modes.mf' (available from ftp://ftp.tug.org/tex/modes.mf), with both `-mnemonics' and `-images' enabled.

GFtype outputs the information about a character in two places: a main definition and a one-line summary at the end. We show both. Here is the main definition:

2033: beginning of char 75: 3<=m<=60 0<=n<=56
(initially n=56) paint (0)24(12)20
2043: newrow 0 (n=55) paint 24(12)20
2047: newrow 0 (n=54) paint 24(12)20
2051: newrow 0 (n=53) paint 24(12)20
2055: newrow 7 (n=52) paint 10(21)13
2059: newrow 8 (n=51) paint 8(23)9
...
2249: newrow 8 (n=5) paint 8(23)11
2253: newrow 7 (n=4) paint 10(22)12
2257: newrow 0 (n=3) paint 24(11)22
2261: newrow 0 (n=2) paint 24(11)22
2265: newrow 0 (n=1) paint 24(11)22
2269: newrow 0 (n=0) paint 24(11)22
2273: eoc
.<--This pixel's lower left corner is at (3,57) in METAFONT coordinates
************************            ********************
************************            ********************
************************            ********************
************************            ********************
**********                     *************
********                       *********
...
********                       ***********
**********                      ************
************************           **********************
************************           **********************
************************           **********************
************************           **********************
.<--This pixel's upper left corner is at (3,0) in METAFONT coordinates

Explanation:

`2033'
`2043'
`...'
The byte position in the file where each GF command starts.
`beginning of char 75'
The character code, in decimal.
`3<=m<=60 0<=n<=56'
The character's bitmap lies between 3 and 60 (inclusive) horizontally, and between 0 and 56 (inclusive) vertically. (m is a column position and n is a row position.) Thus, 3 is the left side bearing. The right side bearing is the horizontal escapement (given below) minus the maximum m.
`(initially n=56) paint (0)24(12)20'
The first row of pixels: 0 white pixels, 24 black pixels, 12 white pixels, etc.
`newrow 0 (n=55) paint 24(12)20'
The second row of pixels, with zero leading white pixels on the row.
`eoc'
The end of the main character definition.

Here is the GF postamble information that GFtype outputs at the end:

Character 75: dx 4259840 (65), width 815562 (64.57289), loc 2033

Explanation:

`dx'
The device-dependent width, in scaled pixels, i.e., units of horizontal pixels times 2^16. The `(65)' is simply the same number rounded. If the vertical escapement is nonzero, it would appear here as a `dy' value.
`width'
The device-independent (TFM) width of this character. It is 2^24 times the ratio of the true width to the font's design size. The `64.57289' is the same number converted to pixels.
`loc'
The byte position in the file where this character starts.

## TFtoPL: TeX font metric to property list conversion

TFtoPL translates a TeX font metric (TFM, see section `Metric files' in Dvips) file (as output by Metafont, for example) to property list format (a list of parenthesized items describing the font) that humans can edit or read. This program is mostly used by people debugging TeX implementations, writing font utilities, etc. Synopsis:

tftopl [option]... tfmname[.tfm] [plfile[.pl]]

The font tfmname (extended with `.tfm' if necessary) is searched for in the usual places (see section `Supported file formats' in Kpathsea). To see all the relevant paths, set the environment variable KPATHSEA_DEBUG to `-1' before running the program.

If plfile (which is extended with `.pl' if necessary) is not specified, the property list file is written to standard output. The property list file can be converted back to TFM format by the companion program TFtoPL (see the next section).

The program accepts the following option, as well as the standard `-verbose', `-help' and `-version' (see section Common options):

`-charcode-format=type'
Output character codes in the PL file according to type: either `octal' or `ascii'. Default is `ascii' for letters and digits, octal for all other characters. Exception: if the font's coding scheme starts with `TeX math sy' or `TeX math ex', all character codes are output in octal. In `ascii' format, character codes that correspond to graphic characters, except for left and right parentheses, are output as a `C' followed by the single character: `C K', for example. In octal format, character codes are output as the letter `O' followed by octal digits, as in `O 113' for `K'. `octal' format is useful for symbol and other non-alphabetic fonts, where using ASCII characters for the character codes is merely confusing.

As an example of the output, here is the (abridged) property list translation of `cmr10.tfm':

(FAMILY CMR)
(FACE O 352)
(CODINGSCHEME TEX TEXT)
(DESIGNSIZE R 10.0)
(COMMENT DESIGNSIZE IS IN POINTS)
(COMMENT OTHER SIZES ARE MULTIPLES OF DESIGNSIZE)
(CHECKSUM O 11374260171)
(FONTDIMEN
(SLANT R 0.0)
(SPACE R 0.333334)
(STRETCH R 0.166667)
(SHRINK R 0.111112)
(XHEIGHT R 0.430555)
(EXTRASPACE R 0.111112)
)
(LIGTABLE
...
(LABEL C f)
(LIG C i O 14)
(LIG C f O 13)
(LIG C l O 15)
(KRN O 47 R 0.077779)
(KRN O 77 R 0.077779)
(KRN O 41 R 0.077779)
(KRN O 51 R 0.077779)
(KRN O 135 R 0.077779)
(STOP)
...
)
...
(CHARACTER C f
(CHARWD R 0.305557)
(CHARHT R 0.694445)
(CHARIC R 0.077779)
(COMMENT
(LIG C i O 14)
(LIG C f O 13)
(LIG C l O 15)
(KRN O 47 R 0.077779)
(KRN O 77 R 0.077779)
...
)
)
...

As you can see, the general format is a list of parenthesized properties, nested where necessary.

• The first few items (FAMILY, FACE, and so on) are the so-called headerbyte information from Metafont, giving general information about the font.
• The FONTDIMEN property defines the TeX \fontdimen values.
• The LIGTABLE property defines the ligature and kerning table. LIG properties define ligatures: in the example above, an `f' (in the `LABEL') followed by an `i' is a ligature, i.e., a typesetting program like TeX replaces those two consecutive characters by the character at position octal '014 in the current font--presumably the `fi' ligature. KRN properties define kerns: if an `f' is followed by character octal '047 (an apostrophe), TeX inserts a small amount of space between them: 0.077779 times the design size the font was loaded at (about three-quarters of a printer's point by default in this case, or .001 inches).
• The CHARACTER property defines the dimensions of a character: its width, height, depth, and italic correction, also in design-size units, as explained in the previous item. For our example `f', the depth is zero, so that property is omitted. TFtoPL also inserts any kerns and ligatures for this character as a comment.

## PLtoTF: Property list to TeX font metric conversion

PLtoTF translates a property list file (as output by TFtoPL, for example) to TeX font metric (TFM, see section `Metric files' in Dvips) format. It's much easier for both programs and humans to create the (plain text) property list files and let PLtoTF take care of creating the binary TFM equivalent than to output TFM files directly. Synopsis:

pltotf [option]... plfile[.pl] [tfmfile[.tfm]]

If tfmfile (extended with `.tfm' if necessary) is not specified, the TFM file is written to the basename of `plfile.tfm', e.g., `pltotf /wherever/cmr10.pl' creates `./cmr10.tfm'. (Since TFM files are binary, writing to standard output by default is undesirable.)

The only options are `-verbose', `-help', and `-version' (see section Common options).

For an example of property list format, see the previous section.

## VFtoVP: Virtual font to virtual property lists

VFtoVP translates a virtual font metric (VF, see section `Virtual fonts' in Dvips) file and its accompanying TeX font metric (TFM, see section `Metric files' in Dvips) file (as output by VPtoVF, for example) to virtual property list format (a list of parenthesized items describing the virtual font) that humans can edit or read. This program is mostly used by people debugging virtual font utilities. Synopsis:

vftovp [option]... vfname[.vf] [tfmname[.tfm] @c
[vplfile[.vpl]]]

The fonts vfname and tfmname (extended with `.vf' and `.tfm' if necessary) are searched for in the usual places (see section `Supported file formats' in Kpathsea). To see all the relevant paths, set the environment variable KPATHSEA_DEBUG to `-1' before running the program. If tfmname is not specified, vfname (without a trailing `.vf') is used.

If vplfile (extended with `.vpl' if necessary) is not specified, the property list file is written to standard output. The property list file can be converted back to VF and TFM format by the companion program VFtoVP (see the next section).

The program accepts the following option, as well as the standard `-verbose', `-help' and `-version' (see section Common options):

`-charcode-format=type'
Output character codes in the PL file according to type: either `octal' or `ascii'. Default is `ascii' for letters and digits, octal for all other characters. Exception: if the font's coding scheme starts with `TeX math sy' or `TeX math ex', all character codes are output in octal. In `ascii' format, character codes that correspond to graphic characters, except for left and right parentheses, are output as a `C' followed by the single character: `C K', for example. In octal format, character codes are output as the letter `O' followed by octal digits, as in `O 113' for `K'. `octal' format is useful for symbol and other non-alphabetic fonts, where using ASCII characters for the character codes is merely confusing.

## VPtoVF: Virtual property lists to virtual font

VPtoVF translates a virtual property list file (as output by VFtoVP, for example) to virtual font (VF, see section `Virtual fonts' in Dvips) and TeX font metric (TFM, see section `Metric files' in Dvips) files. It's much easier for both programs and humans to create the (plain text) property list files and let VPtoVF take care of creating the binary VF and TFM equivalents than to output them directly. Synopsis:

vptovf [option]... vplfile[.vpl] [vffile[.vf] @c
[tfmfile[.tfm]]]

If vffile (extended with `.vf' if necessary) is not specified, the VF file is written to the basename of `vplfile.vf'; similarly for tfmfile. For example, `vptovf /wherever/ptmr.vpl' creates `./ptmr.vf' and `./ptmr.tfm'.

The only options are `-verbose', `-help', and `-version' (see section Common options).

## Font utilities available elsewhere

The Web2c complement of font utilities merely implements a few basic conversions. Many other more sophisticated font utilities exist; most are in `CTAN:/fonts/utilities' (for CTAN info, see section `unixtex.ftp' in Kpathsea). Here are some of the most commonly-requested items:

• AFM (Adobe font metric) to TFM conversion: see section `Invoking afm2tfm' in Dvips, and `CTAN:/fonts/utilities/afmtopl'.
• BDF (the X bitmap format) conversion: ftp://ftp.tug.org/tex/bdf.tar.gz.
• Editing of bitmap fonts: Xbfe from the GNU font utilities mentioned below; the X BDF-editing programs available from ftp://ftp.x.org/R5contrib/xfed.tar.Z and ftp://ftp.x.org/R5contrib/xfedor.tar.Z; and finally, if your fonts have only 128 characters, you can use the old gftopxl, pxtoch, and chtopx programs from ftp://ftp.tug.org/tex/web.
• PK bitmaps from PostScript fonts: gsftopk from the `xdvik' distribution or from `CTAN:/fonts/utilities/gsftopk'; alternatively, ps2pk, from `CTAN:/fonts/utilities/ps2pk'.
• PostScript Type 1 font format conversion (i.e., between PFA and PFB formats): ftp://ftp.tug.org/tex/t1utils.tar.gz.
• Scanned image conversion: the (aging) GNU font utilities convert type specimen images to Metafont, PostScript, etc.: ftp://prep.ai.mit.edu/pub/gnu/fontutils-0.6.tar.gz.
• Virtual font creation: `CTAN:/fonts/utilities/fontinst'.