Go to the first, previous, next, last section, table of contents.


5. TeX searching

Although the basic features in Kpathsea can be used for any type of path searching, it came about (like all libraries) with a specific application in mind: I wrote Kpathsea specifically for TeX system programs. I had been struggling with the programs I was using (Dvips, Xdvi, and TeX itself) having slightly different notions of how to specify paths; and debugging was painful, since no code was shared.

Therefore, Kpathsea provides some TeX-specific features. Indeed, many of the supposedly generic path searching features were provided because they seemed useful in that conTeXt (font lookup, particularly).

5.1 TeX environment variables

Kpathsea defines a sequence of environment variables to search for each file type it supports. This makes it easy for different programs to check the same environment variables, in the same order.

The following table lists the environment variables searched for each file type in the order they are searched (and a brief description of the file type). That is, only if the first variable is unset is the second variable checked, and so on. If none are set, various other things are checked; see section 4.2 Path sources.

`.base'
(Metafont memory dump) `MFBASES'
`.bib'
(BibTeX bibliography source) `BIBINPUTS'
`.bst'
(BibTeX style file) `BSTINPUTS', `TEXINPUTS'
`.cnf'
(Kpathsea runtime configuration files) `TEXMFCNF'
`.eps'
(Encapsulated PostScript figures) `TEXPICTS', `TEXINPUTS'
`.fmt'
(TeX memory dump) `TEXFORMATS'
`gf'
(generic font bitmap) `programFONTS', `GFFONTS', `GLYPHFONTS', `TEXFONTS'
`.mf'
(Metafont source) `MFINPUTS'
`mf.pool'
(Metafont program strings) `MFPOOL'
`.pict'
(Other kinds of figures) Same as `.eps'.
`pk'
(packed bitmap font) `programFONTS', `PKFONTS', `TEXPKS', `GLYPHFONTS', `TEXFONTS'
`.tex'
(TeX source) `TEXINPUTS'
`tex.pool'
(TeX program strings) `TEXPOOL'
`.tfm'
(TeX font metrics) `TFMFONTS', `TEXFONTS'
`.vf'
(virtual font) `VFFONTS', `TEXFONTS'

For the font variables, the intent is that:

  1. `TEXFONTS' is the default for everything.
  2. `GLYPHFONTS' is the default for bitmap (or, more precisely, non-metric) files.
  3. Each format has its own variable.
  4. Each program can and should have its own font override path as well; e.g., `DVIPSFONTS' for Dvipsk. Again, this is for bitmaps, not metrics.

If these environment variables are set, the corresponding `texmf.cnf' definition won't be looked at (unless, as usual, the environment variable has an extra `:'). See section 4.3 Default expansion.

5.2 Glyph lookup

Kpathsea provides a routine (kpse_find_glyph_format in `kpathsea/tex-glyph.c') which searches for a bitmap font in GF or PK format (or either) given a font name (e.g., `cmr10') and a resolution (e.g., 300).

The search is based solely on filenames, not file contents--if a PK file is named `cmr10.300gf', it will be found as a GF file.

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.

  1. Look for an existing file name.dpi in the specified format(s).
  2. If name is an alias for a file f in the fontmap file `texfonts.map', look for f.dpi.
  3. Run an external script (typically named MakeTeXPK) to generate the font.
  4. Look for fallback.dpi, where fallback is some last-resort font (typically `cmr10').

5.2.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.300pk'. Kpathsea looks for a PK file first, then a GF file.

If that fails, Kpathsea looks for `dpidpi/name.format'; for example, `dpi300/cmr10.pk'. This is how fonts are typically stored on filesystems (like DOS's) 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, which is slightly more than the 0.2% allowed by the DVI standard.

5.2.2 Fontmap

If a bitmap font 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 are searched for along the usual glyph path.

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 `Adobe-Lucida-Bold-Sans=Typewriter' instead of `plcbst', you can.
  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: the first word on each line is the true filename; the second word is the alias; subsequent words are ignored. A word is a sequence of non-whitespace characters. Blank lines are ignored; comments start with `%' and continue to end-of-line.

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 exactly `foo.tfm' is being searched for; but an alias `foo' matches `foo.vf', `foo.300pk', etc.

As an example, here are the fontmap entries that make the circle fonts equivalent. These are in the distributed `texfonts.map' in the Web2C distribution.

circle10	lcircle10
circle10	lcirc10
lcircle10	circle10
lcircle10	lcirc10
lcirc10		circle10
lcirc10		lcircle10

5.2.3 `MakeTeX'... scripts

If Kpathsea cannot find a bitmap font, by either its original name or a fontmap alias, it can be configured to invoke an external program to create it. The same mechanism can be used for other nonexistent files.

The script is passed the name of the file to create and possibly other arguments, as explained below. It must echo the full pathname of the file it created (and nothing else) to standard output; it can write diagnostics to standard error.

5.2.3.1 `MakeTeX'... script names

The following table shows the default name of the script for each possible file types. (The source is the variable kpse_make_specs in `kpathsea/tex-make.c'.)

`MakeTeXPK'
Glyph fonts.
`MakeTeXTeX'
TeX input files.
`MakeTeXMF'
Metafont input files.
`MakeTeXTFM'
TFM files.

These names are overridden by an environment variable specific to the program--for example, `DVIPSMAKEPK' for Dvipsk.

If a MakeTeX... script fails, the invocation is appended to a file `missfont.log' in the current directory. If the current directory is not writable and the environment variable `TEXMFOUTPUT' is set, its value is used. Otherwise, nothing is written.

5.2.3.2 `MakeTeX'... script arguments

The first argument to a `MakeTeX'... script is always the name of the file to be created.

For `MakeTeXPK', three or four additional arguments are also passed, via corresponding environment variables:

  1. The dpi to make the font at (`KPATHSEA_DPI').
  2. The "base dpi" the program is operating at (`MAKETEX_BASE_DPI'), i.e., the assumed resolution of the output device.
  3. A "magstep" string suitable for the Metafont mag variable (`MAKETEX_MAG').
  4. Optionally, a Metafont mode name to assign to the Metafont mode variable (`MAKETEX_MODE'). Otherwise, (the default) MakeTeXPK guesses the mode from the resolution. See section 6. TeX directory structure.
  5. Optionally, a directory name. If the directory is absolute, it is used as-is. Otherwise, it is appended to the root destination directory set in the script (from environment variables DESTDIR or MTP_DESTDIR or a compile-time default). If this argument is not supplied, the mode name is appended to the root destination directory.

Kpathsea sets `KPATHSEA_DPI' appropriately for each attempt at building a font. It's up to the program using Kpathsea to set the others. (See section 7.2 Calling sequence.)

You can change the specification for the arguments passed to the external script by setting the environment variable named as the script name, but all capitals---`MAKETEXPK', for example. If you've changed the script name by setting (say) `DVIPSMAKEPK' to `foo', then the spec is taken from the environment variable `FOO'.

The spec can contain any variable references, to the above variables or any others you might have set. As an example, the default spec for MakeTeXPK is:

$KPATHSEA_DPI $MAKETEX_BASE_DPI $MAKETEX_MAG $MAKETEX_MODE

The convention of passing the name of the file to be created as the first argument cannot be changed.

5.2.4 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 assigning to the global variable kpse_fallback_font or calling kpse_init_prog (see section 7.2 Calling sequence); the default is no such fallback font.


Go to the first, previous, next, last section, table of contents.