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).
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.
For the font variables, the intent is that:
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.
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.
MakeTeXPK
) to
generate the font.
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.
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:
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
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.
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'.)
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.
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:
mag
variable
(`MAKETEX_MAG').
mode
variable (`MAKETEX_MODE'). Otherwise, (the default)
MakeTeXPK
guesses the mode from the resolution. See section 6. TeX directory structure.
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.
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.