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 formats and features.
Indeed, many of the supposedly generic path searching features were
provided because they seemed useful in that conTeXt (font lookup,
particularly).

Kpathsea provides a standard way to search for files of any of the
supported file types; glyph fonts are a bit different than all the rest.
Searches are based solely on filenames, not file contents--if a GF
file is named `cmr10.600pk', it will be found as a PK file.

Kpathsea has support for a number of file types. Each file type has a
list of environment and config file variables that are checked to define
the search path, and most have a default suffix that plays a role in
finding files (see the next section). Some also define additional
suffixes, and/or a program to be run to create missing files on the fly.

Since environment variables containing periods, such as
`TEXINPUTS.latex', are not allowed on some systems, Kpathsea looks
for environment variables with an underscore, e.g.,
`TEXINPUTS_latex' (see section Config files).

There are two special cases, because the paths and environment variables
always depend on the name of the program: the variable name is
constructed by converting the program name to upper case, and then
appending `INPUTS'. Assuming the program is called `foo',
this gives us the following table.

`other text files'

(text files used by `foo')
FOOINPUTS.

`other binary files'

(binary files used by `foo')
FOOINPUTS.

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

For the font variables, the intent is that:

TEXFONTS is the default for everything.

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

Each font format has a variable of its own.

Each program has its own font override path as well; e.g.,
DVIPSFONTS for Dvipsk. Again, this is for bitmaps, not metrics.

This section describes how Kpathsea searches for most files (bitmap font
searches are the exception, as described in the next section).

Here is the search strategy for a file name:

If the file format defines default suffixes, and the suffix of
name name is not already a known suffix for that format, try the
name with each default appended, and use alternative names found in the
fontmaps if necessary. We postpone searching the disk as long as
possible. Example: given `foo.sty', look for `foo.sty.tex'
before `foo.sty'. This is unfortunate, but allows us to find
`foo.bar.tex' before `foo.bar' if both exist and we were given
`foo.bar'.

Search for name, and if necssary for alternative names found in
the fontmaps. Again we avoid searching the disk if possible. Example:
given `foo', we look for `foo'.

If the file format defines a program to invoke to create missing files,
run it (see section `mktex' scripts).

This is implemented in the routine kpse_find_file in
`kpathsea/tex-file.c'. You can watch it in action with the
debugging options (see section Debugging).

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

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:

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').

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 `%' and continue to the end of the line.

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 circle fonts equivalent and includes
automatically generated maps for most PostScript fonts available from
various font suppliers.

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 Calling sequence); the default is no fallback font.

Kpathsea provides a way to suppress selected usually-harmless warnings;
this is useful at large sites where most users are not administrators,
and thus the warnings are merely a source of confusion, not a help. To
do this, you set the environment variable or configuration file value
TEX_HUSH to a colon-separated list of values. Here are the
possibilities:

`all'

Suppress everything possible.

`checksum'

Suppress mismatched font checksum warnings.

`lostchar'

Suppress warnings when a character is missing from a font that a DVI or
VF file tries to typeset.

`readable'

Suppress warnings about attempts to access a file whose permissions
render it unreadable.

`special'

Suppresses warnings about an unimplemented or unparsable
`\special' command.

`tex-hush.c' defines the function that checks the
variable value. Each driver implements its own checks where
appropriate.