info > (kpathsea)Glyph lookup

man perldoc info pydoc3 ri search

📖 NAME

Glyph lookup – How Kpathsea searches for a bitmap font in GF or PK format given a font name and resolution.

🚀 Quick Reference

Use Case	Command / Variable	Description
🔎 Find existing bitmap font	kpathsea_find_glyph	Search for a font file NAME.DPIFORMAT or dpiDPI/NAME.FORMAT
🔗 Look up font alias	texfonts.map via TEXFONTMAPS	Map alternate names to actual font files
⚙️ Generate missing font	mktexpk	Run external program to create the font bitmap
🔄 Fallback resolution	DVIPSSIZES, TEXSIZES, default_texsizes	Try scaled sizes when exact DPI is not found
🆘 Last-resort font	cmr10 (fallback)	Use a standard fallback font if all else fails

🔍 6.3 Glyph lookup

This section describes how Kpathsea searches for a bitmap font in GF or PK format (or either) given a font name (e.g., cmr10) and a resolution (e.g., 600).

🔎 Here is an outline of the search strategy (details in the sections below) for a file NAME at resolution DPI. The search stops at the first successful lookup.

• 🔎 Look for an existing file NAME.DPIFORMAT in the specified format(s).
• 🔗 If NAME is an alias for a file F in the fontmap file texfonts.map, look for F.DPI.
• ⚙️ Run an external program (typically named mktexpk) to generate the font (mktex scripts).
• 🔄 Look for FALLBACK.DPI, where FALLBACK is some last-resort font (typically cmr10).

This is implemented in kpathsea_find_glyph in kpathsea/tex-glyph.c.

• Basic glyph lookup
• Fontmap
• Fallback font

🔍 6.3.1 Basic glyph lookup

When Kpathsea looks for a bitmap font NAME at resolution DPI in a format FORMAT, it first checks each directory in the search path for a file NAME.DPIFORMAT; for example, cmr10.600pk. Kpathsea looks for a PK file first, then a GF file.

• 📁 If that fails, Kpathsea looks for dpiDPI/NAME.FORMAT; for example, dpi600/cmr10.pk. This is how fonts are typically stored on filesystems (such as DOS) that permit only three-character extensions.
• 📏 If that fails, Kpathsea looks for a font with a close-enough DPI. “Close enough” is defined by the macro KPSE_BITMAP_TOLERANCE in kpathsea/tex-glyph.h to be DPI / 500 + 1. This is slightly more than the 0.2% minimum allowed by the DVI standard (<CTAN:/dviware/driv-standard/level-0>).

🔗 6.3.2 Fontmap

If a bitmap font or metric file is not found with the original name (see the previous section), Kpathsea looks through any “fontmap” files for an “alias” for the original font name. These files are named texfonts.map and searched for along the TEXFONTMAPS environment/config file variable. All texfonts.map files that are found are read; earlier definitions override later ones.

This feature is intended to help in two respects:

1. 📝 An alias name is limited in length only by available memory, not by your filesystem. Therefore, if you want to ask for Times-Roman instead of ptmr, you can (you get ptmr8r).
2. 🔄 A few fonts have historically had multiple names: specifically, LaTeX’s “circle font” has variously been known as circle10, lcircle10, and lcirc10. Aliases can make all the names equivalent, so that it no longer matters what the name of the installed file is; TeX documents will find their favorite name.

The format of fontmap files is straightforward:

• 💬 Comments start with the last % on a line and continue to the end of the line. (This provides for names that include a %, ill-advised as that may be.)
• 📄 Blank lines are ignored.
• 🔤 Each nonblank line is broken up into a series of “words”: a sequence of non-whitespace characters.
• 📂 If the first word is include, the second word is used as a filename, and it is searched for and read.
• 📛 Otherwise, the first word on each line is the true filename; the second word is the alias; subsequent words are ignored.

If an alias has an extension, it matches only those files with that extension; otherwise, it matches anything with the same root, regardless of extension. For example, an alias foo.tfm matches only when foo.tfm is being searched for; but an alias foo matches foo.vf, foo.600pk, etc.

📄 As an example, here is an excerpt from the texfonts.map in the Web2c distribution. It makes the old and new names of the LaTeX circle fonts equivalent.

circle10        lcircle10
circle10        lcirc10
lcircle10       circle10
lcircle10       lcirc10
lcirc10         circle10
lcirc10         lcircle10
...

Fontmaps are implemented in the file kpathsea/fontmap.c. The Fontname distribution has much more information on font naming (fontname).

🔄 6.3.3 Fallback font

If a bitmap font cannot be found or created at the requested size, Kpathsea looks for the font at a set of “fallback resolutions”. You specify these resolutions as a colon-separated list (like search paths). Kpathsea looks first for a program-specific environment variable (e.g., DVIPSSIZES for Dvipsk), then the environment variable TEXSIZES, then a default specified at compilation time (the Make variable default_texsizes). You can set this list to be empty if you prefer to find fonts at their stated size or not at all.

Finally, if the font cannot be found even at the fallback resolutions, Kpathsea looks for a fallback font, typically cmr10. Programs must enable this feature by calling kpathsea_init_prog (Calling sequence); the default is no fallback font.

📖 NAME 🚀 Quick Reference 🔍 6.3 Glyph lookup