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

4. TeX support

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.

4.1 Supported file formats

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.

(Adobe font metrics, see section `Metric files' in Dvips) AFMFONTS; suffix `.afm'.
(Metafont memory dump, see section `Memory dumps' in Web2c) MFBASES, TEXMFINI; suffix `.base'.
(BibTeX bibliography source, see section `bibtex invocation' in Web2c) BIBINPUTS, TEXBIB; suffix `.bib'.
(BibTeX style file, see section `Basic BibTeX style files' in Web2c) BSTINPUTS; suffix `.bst'.
(Runtime configuration files, see section 3.2.1 Config files) TEXMFCNF; suffix `.cnf'.
`dvips config'
(Dvips `config.*' files, such as `config.ps', see section `Config files' in Dvips) TEXCONFIG.
(TeX memory dump, see section `Memory dumps' in Web2c) TEXFORMATS, TEXMFINI; suffix `.fmt'.
(generic font bitmap, see section `Glyph files' in Dvips) programFONTS, GFFONTS, GLYPHFONTS, TEXFONTS; suffix `gf'.
(Encapsulated PostScript figures, see section `PostScript figures' in Dvips) TEXPICTS, TEXINPUTS; additional suffixes: `.eps', `.epsi'.
(makeindex style files) TEXINDEXSTYLE, INDEXSTYLE; suffix `.ist'.
(Filename databases, see section 3.4 Filename database (ls-R)) TEXMFDBS.
(Fontmaps, see section 4.3.2 Fontmap) TEXFONTMAPS; suffix `.map'.
(MetaPost memory dump, see section `Memory dumps' in Web2c) MPMEMS, TEXMFINI; suffix `.mem'.
`MetaPost support'
(MetaPost support files, used by DMP; see section `dmp invocation' in Web2c) MPSUPPORT.
(Metafont source, see section `mf invocation' in Web2c) MFINPUTS; suffix `.mf'; dynamic creation program: mktexmf.
(Metafont program strings, see section `pooltype invocation' in Web2c) MFPOOL, TEXMFINI; suffix `.pool'.
(MFT style file, see section `mft invocation' in Web2c) MFTINPUTS; suffix `.mft'.
(MetaPost source, see section `mpost invocation' in Web2c) MPINPUTS; suffix `.mp'.
(MetaPost program strings, see section `pooltype invocation' in Web2c) MPPOOL, TEXMFINI; suffix `.pool'.
(Omega compiled process files) OCPINPUTS;
suffix `.ocp'; dynamic creation program: MakeOmegaOCP.
(Omega font metrics) OFMFONTS, TEXFONTS;
suffixes `.ofm', `.tfm'; dynamic creation program: MakeOmegaOFM.
(Omega property lists) OPLFONTS, TEXFONTS; suffix `.opl'.
(Omega translation process files) OTPINPUTS; suffix `.otp'.
(Omega virtual fonts) OVFFONTS, TEXFONTS; suffix `.ovf'.
(Omega virtual property lists) OVPFONTS, TEXFONTS; suffix `.ovp'.
(packed bitmap fonts, see section `Glyph files' in Dvips) PROGRAMFONTS (program being `XDVI', etc.), PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS; suffix `pk'; dynamic creation program: mktexpk.
`PostScript header'
(downloadable PostScript, see section `Header files' in Dvips) TEXPSHEADERS, PSHEADERS; additional suffix `.pro'.
(TeX source, see section `tex invocation' in Web2c) TEXINPUTS; suffix `.tex'; additional suffixes: none, because such a list cannot be complete; dynamic creation program: mktextex.
`TeX system documentation'
(Documentation files for the TeX system) TEXDOCS.
`TeX system sources'
(Source files for the TeX system) TEXSOURCES.
(TeX program strings, see section `pooltype invocation' in Web2c) TEXPOOL, TEXMFINI; suffix `.pool'.
(TeX font metrics, see section `Metric files' in Dvips) TFMFONTS, TEXFONTS; suffix `.tfm'; dynamic creation program: mktextfm.
`Troff fonts'
(Troff fonts, used by DMP; see section `DMP invocation' in Web2c) TRFONTS.
`truetype fonts'
(TrueType outline fonts) TTFONTS; suffixes `.ttf', `.ttc'.
`type1 fonts'
(Type 1 PostScript outline fonts, see section `Glyph files' in Dvips) T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS; suffixes `.pfa', `.pfb'.
`type42 fonts'
(Type 42 PostScript outline fonts) T42FONTS.
(virtual fonts, see section `Virtual fonts' in Dvips) 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.

`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 3.3.1 Default expansion.

For the font variables, the intent is that:

4.2 File lookup

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:

  1. 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'.
  2. Search for name, and if necessary for alternative names found in the fontmaps. Again we avoid searching the disk if possible. Example: given `foo', we look for `foo'.
  3. If the file format defines a program to invoke to create missing files, run it (see section 2.2.9 `mktex' scripts).

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

4.3 Glyph lookup

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.

  1. Look for an existing file name.dpiformat 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 program (typically named `mktexpk') to generate the font (see section 2.2.9 `mktex' scripts)
  4. Look for fallback.dpi, where fallback is some last-resort font (typically `cmr10').

This is implemented in kpse_find_glyph_format in `kpathsea/tex-glyph.c'.

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

4.3.2 Fontmap

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:

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

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

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

4.4 Suppressing warnings

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:

Suppress everything possible.
Suppress mismatched font checksum warnings.
Suppress warnings when a character is missing from a font that a DVI or VF file tries to typeset.
Don't suppress any warnings.
Suppress warnings about attempts to access a file whose permissions render it unreadable.
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.

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