TeX support
***********

Although the basic features in Kpathsea can be used for any type of path searching, 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 it seemed useful in conTeXt, particularly for font lookup.

TeX environment variables
=========================

Kpathsea defines a sequence of environment variables to search for each type of TeX file.  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, a default set at compilation time is used.

.base
     (Metafont memory dump) MFBASES

.bib
     (BibTeX source) BIBINPUTS

.bst
     (BibTeX style file) BSTINPUTS, TEXINPUTS

.fmt
     (TeX memory dump) TEXFORMATS

gf
     (generic font bitmap) GFFONTS, GLYPHFONTS, TEXFONTS

.mf
     (Metafont source) MFINPUTS

mf.pool
     (Metafont program strings) MFPOOL

pk
     (packed bitmap font) 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

These lists are defined in the source file kpathsea/filefmt.h.

For the font variables, the intent is that:

 1. TEXFONTS is the default for everything.

 2. GLYPHFONTS the default for bitmap (or, more precisely, non-metric) files.

 3. Each format has its own variable.

 4. Not shown in the table is that each program can and should have its own path as well---XDVIFONTS and DVIPSFONTS in the case of Xdvik and Dvipsk.

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 formats.

 2. If NAME is an alias for a file A in some ``fontmap'' file, look for A.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).

Basic glyph lookup
------------------

When Kpathsea looks for a bitmap font NAME at resolution DPI in a format FORMAT, it first checks if a file NAME.DPIFORMAT exists; for example, cmr10.300pk.  Kpathsea looks for a PK file first, then a GF file.

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.

The filename is not hardwired to NAME.DPIFORMAT; you can change it by setting the environment variable KPATHSEA_BITMAP_NAME to a different specification.  The default spec is

     $KPATHSEA_NAME.$KPATHSEA_DPI$KPATHSEA_FORMAT

Kpathsea sets these environment variables as it runs, as appropriate for each lookup.  You can use any environment variables you like, not just these, in the spec.

Fontmap
-------

If a bitmap font is not found, Kpathsea looks through any fontmap files for an alias for the original font name.  I implemented this for two reasons:

 1. An alias name is limited in length only by your available memory, not by whatever bizarre limitations your filesystem might impose.  Therefore, if you want to ask for Adobe-Lucida-Bold-Sans=Typewriter--10 instead of plcbst10, 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 that implement these ideas 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 just 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, or whatever.

As an example, here are the fontmap entries that make the circle fonts equivalent:

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

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.

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---DVIPSMAKEPK and XDVIMAKEPK, in the case of Dvipsk and Xdvik.

MakeTeX... script arguments
...........................

The first argument to a MakeTeX... script is always the name of the file to be created.  In the case of MakeTeXPK, there are three or four additional arguments 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).

 3. A ``magstep'' string suitable for assigning to the Metafont mag variable (MAKETEX_MAG).

 4. Possibly, a Metafont mode name for assigning to the Metafont mode variable (MAKETEX_MODE).

Kpathsea sets KPATHSEA_DPI appropriately for each font. It's up to the program using Kpathsea to set the others.

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 name of the file to be created being passed as the first argument cannot be changed.

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 (DVIPSSIZES and XDVISIZES, in the case of Dvipsk and Xdvik), 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; the default is no such fallback font.