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 3.2.1 Config files).
The following table lists the above information.
AFMFONTS;
suffix `.afm'.
MFBASES, TEXMFINI;
suffix `.base'.
BIBINPUTS, TEXBIB;
suffix `.bib'.
BSTINPUTS;
suffix `.bst'.
TEXMFCNF;
suffix `.cnf'.
TEXCONFIG.
TEXFORMATS, TEXMFINI;
suffix `.fmt'.
programFONTS, GFFONTS, GLYPHFONTS, TEXFONTS;
suffix `gf'.
TEXPICTS, TEXINPUTS;
additional suffixes: `.eps', `.epsi'.
TEXINDEXSTYLE, INDEXSTYLE;
suffix `.ist'.
ls-R))
TEXMFDBS.
TEXFONTMAPS;
suffix `.map'.
MPMEMS, TEXMFINI;
suffix `.mem'.
MPSUPPORT.
MFINPUTS;
suffix `.mf';
dynamic creation program: mktexmf.
MFPOOL, TEXMFINI;
suffix `.pool'.
MFT style file, see section `mft invocation' in Web2c)
MFTINPUTS;
suffix `.mft'.
MPINPUTS;
suffix `.mp'.
MPPOOL, TEXMFINI;
suffix `.pool'.
OCPINPUTS; MakeOmegaOCP.
OFMFONTS, TEXFONTS; MakeOmegaOFM.
OPLFONTS, TEXFONTS;
suffix `.opl'.
OTPINPUTS;
suffix `.otp'.
OVFFONTS, TEXFONTS;
suffix `.ovf'.
OVPFONTS, TEXFONTS;
suffix `.ovp'.
PROGRAMFONTS (program being `XDVI', etc.),
PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS;
suffix `pk';
dynamic creation program: mktexpk.
TEXPSHEADERS, PSHEADERS;
additional suffix `.pro'.
TEXINPUTS;
suffix `.tex';
additional suffixes: none, because such a list cannot be complete;
dynamic creation program: mktextex.
TEXDOCS.
TEXSOURCES.
TEXPOOL, TEXMFINI;
suffix `.pool'.
TFMFONTS, TEXFONTS;
suffix `.tfm';
dynamic creation program: mktextfm.
TRFONTS.
TTFONTS; suffixes `.ttf',
`.ttc'.
T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS;
suffixes `.pfa', `.pfb'.
T42FONTS.
VFFONTS, TEXFONTS;
suffix `.vf'.
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.
FOOINPUTS.
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 3.3.1 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.
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:
You can change the policy by setting the variable allow_multiple_suffixes to false either in your environment or in the file `texmf.cnf'. In this case, if the name looked for has already a suffix (dot plus three characters), only this name will be looked for, no matter if the suffix is known or not. If the name has no suffix, the search reverts to the previous policy.
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 2.6.3 Debugging).
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.
This is implemented in kpse_find_glyph_format in
`kpathsea/tex-glyph.c'.
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:
The format of fontmap files is straightforward:
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.
circle10 lcircle10 circle10 lcirc10 lcircle10 circle10 lcircle10 lcirc10 lcirc10 circle10 lcirc10 lcircle10 ... include adobe.map include apple.map include bitstrea.map ...
Fontmaps are implemented in the file `kpathsea/fontmap.c'. The Fontname distribution has much more information on font naming (see section `Introduction' in Filenames for TeX fonts).
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 5.2 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:
`tex-hush.c' defines the function that checks the variable value. Each driver implements its own checks where appropriate.
Go to the first, previous, next, last section, table of contents.