CONFIGURING TEX4HT WITH KPATHSEA

(revised for v.20030426-1 of Debian tex4ht package)

The Debian and Fedora packaged versions of the tex4ht programs are compiled with support
for the kpathsea file searching library.  This ensures that the main
configuration of the programs uses the same system as other programs in the
TeX family, and so should be reasonably familiar to TeX-admins.

From version 20030426-1, the use of the kpathsea routines and their
relationship with tex4ht-specific configuration options is better documented.
This file attempts to briefly summarise the file searching options and the
implications of using the kpathsea library.  Full details are spread through
the HTML documentation and the tex4ht files.

FINDING TEX4HT FILES USING KPATHSEA

The following are the kinds of files that require to be found by the tex4ht
programs (i.e. by tex4ht and t4ht):

1. TFM font metric files (*.tfm)
2. HTF hypertext font definition files (*.htf)
3. The tex4ht.env configuration file

Using kpathsea, these files are found as follows:

1. TFM fonts are found in the same way as by tex/latex, using the TFMFONTS
variable from texmf.cnf (this should already be set up in your texmf.cnf by
the tetex-bin package).  

The tex4ht-specific methods of specifying paths for TFM fonts are not used and
will be ignored.

2. HTF fonts are found using the TEX4HTINPUTS, T4HTINPUTS and (optionally)
TEX4HTFONTSET variables from texmf.cnf, and are in any case stored in the
default location for the TEX4HTINPUTS variable.  As the default texmf.cnf
shipped with tetex-bin includes the T4HTINPUTS variable, none of these needs
setting.  However, the tex4ht package updates the texmf.cnf file to include
suitable settings for these variables, so that HTF fonts can be found
automatically.  

The tex4ht-specific methods of specifying paths for HTF fonts are, however,
still supported, and may be needed to specify alternative versions of the HTF
fonts (e.g. for MathML output).  These methods and their use in a
kpathsea-enabled tex4ht/t4ht are summarised below.

3. The tex4ht.env configuration file (used for defining the method of
generating bitmaps for symbol characters and pictorial content, among other
things), will be found in the correct location for the TEX4HTINPUTS/T4HTINPUTS
variable of texmf.cnf.  If you want to use an alternative config file, you can
either put it in one of the default places to be found by kpathsea (such as in
~/texmf/tex4ht), or you can use the '-e' command-line switch to the programs
to specify its location (such as '-e/usr/local/tex4ht.env':  note that no
space should be left between the '-e' and the path name).

SPECIFYING ALTERNATIVE LOCATIONS FOR FILES

The tex4ht programs include two ways of specifying alternative locations for
files:

a.) with command-line switches (-i, -t)
b.) with directives in the tex4ht.env configuration file

The kpathsea-enabled programs observe both these methods for finding
alternative versions of HTF files, but in a slightly subtle way, viz:

a.) The command-line switches work as expected, thus use
'-i/usr/share/texmf/tex4ht/unicode/!' to use the Unicode HTF fonts (the '!' is
tex4ht's method of specifying recursive subdirectory searching).

b.) Directives ('i' lines) in tex4ht.env that point to actual directories will
work as expected.  Directives in tex4ht.env that point to directories that do
not exist will still work, so long as the directives point to directories that
include an 'ht-fonts' component.  In these cases, the exact path given in
tex4ht.env will be ignored, and the subdirectory component(s) following the
'ht-fonts' will be added to the paths specified in texmf.cnf to find the
fonts.  This means that, even if the HTF directory tree is moved to another
place within the filesystem, the 'i' directives within tex4ht.env should still
work without needing to be changed.

The kpathsea-enabled programs ignore both the '-t' command-line switches and
the 't' directives in tex4ht.env (for finding TFM fonts).  They also ignore
any '-l' switch or 'l' directive and do not use tex4ht's own bookkeeping file.
(The non-kpathsea-enabled version of tex4ht uses a cache tex4ht.fls of its own
to speed up file searches.)


Andrew Gray <ajpg@debian.org>,
Tue, 13 May 2003 21:28:22 +0100
(Written for the Debian package of tex4ht, but may be used by others.)