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.

- Supported file formats: File types Kpathsea knows about.
- File lookup: Searching for most kinds of files.
- Glyph lookup: Searching for bitmap fonts.
- Suppressing warnings: Avoiding warnings via TEX_HUSH.

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

``afm'`
  (Adobe font metrics, see section `Metric files' in Dvips) `AFMFONTS`; suffix ``.afm'`.
``base'`
  (Metafont memory dump, see section `Memory dumps' in Web2c) `MFBASES`, `TEXMFINI`; suffix ``.base'`.
``bib'`
  (BibTeX bibliography source, see section `bibtex invocation' in Web2c) `BIBINPUTS`, `TEXBIB`; suffix ``.bib'`.
``bst'`
  (BibTeX style file, see section `Basic BibTeX style files' in Web2c) `BSTINPUTS`; suffix ``.bst'`.
``cnf'`
  (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`.
``fmt'`
  (TeX memory dump, see section `Memory dumps' in Web2c) `TEXFORMATS`, `TEXMFINI`; suffix ``.fmt'`.
``gf'`
  (generic font bitmap, see section `Glyph files' in Dvips) `programFONTS`, `GFFONTS`, `GLYPHFONTS`, `TEXFONTS`; suffix ``gf'`.
``graphic/figure'`
  (Encapsulated PostScript figures, see section `PostScript figures' in Dvips) `TEXPICTS`, `TEXINPUTS`; additional suffixes: ``.eps'`, ``.epsi'`.
``ist'`
  (makeindex style files) `TEXINDEXSTYLE`, `INDEXSTYLE`; suffix ``.ist'`.
``ls-R'`
  (Filename databases, see section 3.4 Filename database (`ls-R`)) `TEXMFDBS`.
``map'`
  (Fontmaps, see section 4.3.2 Fontmap) `TEXFONTMAPS`; suffix ``.map'`.
``mem'`
  (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`.
``mf'`
  (Metafont source, see section `mf invocation' in Web2c) `MFINPUTS`; suffix ``.mf'`; dynamic creation program: `mktexmf`.
``mfpool'`
  (Metafont program strings, see section `pooltype invocation' in Web2c) `MFPOOL`, `TEXMFINI`; suffix ``.pool'`.
``mft'`
  (`MFT` style file, see section `mft invocation' in Web2c) `MFTINPUTS`; suffix ``.mft'`.
``mp'`
  (MetaPost source, see section `mpost invocation' in Web2c) `MPINPUTS`; suffix ``.mp'`.
``mppool'`
  (MetaPost program strings, see section `pooltype invocation' in Web2c) `MPPOOL`, `TEXMFINI`; suffix ``.pool'`.
``ocp'`
  (Omega compiled process files) `OCPINPUTS`;
  suffix ``.ocp'`; dynamic creation program: `MakeOmegaOCP`.
``ofm'`
  (Omega font metrics) `OFMFONTS`, `TEXFONTS`;
  suffixes ``.ofm'`, ``.tfm'`; dynamic creation program: `MakeOmegaOFM`.
``opl'`
  (Omega property lists) `OPLFONTS`, `TEXFONTS`; suffix ``.opl'`.
``otp'`
  (Omega translation process files) `OTPINPUTS`; suffix ``.otp'`.
``ovf'`
  (Omega virtual fonts) `OVFFONTS`, `TEXFONTS`; suffix ``.ovf'`.
``ovp'`
  (Omega virtual property lists) `OVPFONTS`, `TEXFONTS`; suffix ``.ovp'`.
``pk'`
  (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'`
  (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`.
``texpool'`
  (TeX program strings, see section `pooltype invocation' in Web2c) `TEXPOOL`, `TEXMFINI`; suffix ``.pool'`.
``tfm'`
  (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`.
``vf'`
  (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:

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

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

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.dpi format 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'`.

- Basic glyph lookup: Features common to all glyph lookups.
- Fontmap: Aliases for fonts.
- Fallback font: Resolutions and fonts of last resort.

### 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:

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

    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:

``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.
``none'`
  Don't suppress any warnings.
``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.

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