kpathsea: Config files
5.2.1 Config files
------------------
As mentioned above, Kpathsea reads "runtime configuration files" named
'texmf.cnf' for search path and other definitions. The search path used
to look for these configuration files is named 'TEXMFCNF', and is
constructed in the usual way, as described above, except that
configuration files cannot be used to define the path, naturally; also,
an 'ls-R' database is not used to search for them.
Kpathsea reads _all_ 'texmf.cnf' files in the search path, not just
the first one found; definitions in earlier files override those in
later files. Thus, if the search path is '.:$TEXMF', values from
'./texmf.cnf' override those from '$TEXMF/texmf.cnf'.
If Kpathsea cannot find any 'texmf.cnf' file, it reports a warning
including all the directories it checked. If you don't want to see this
warning, set the environment variable 'KPATHSEA_WARNING' to the single
character '0' (zero, not oh).
While (or instead of) reading this description, you may find it
helpful to look at the distributed 'texmf.cnf', which uses or at least
mentions most features. The format of 'texmf.cnf' files follows:
* Comments start with '%', either at the beginning of a line or
preceded by whitespace, and continue to the end of the line. That
is, as with most shells, a '%' in the "middle" of a value does not
start a comment. Examples:
% this is a comment
var = a%b % but the value of var will be "a%b".
* Blank lines are ignored.
* A '\' at the end of a line acts as a continuation character, i.e.,
the next line is appended. Whitespace at the beginning of
continuation lines is not ignored.
* Each remaining line must look like
VARIABLE [. PROGNAME] [=] VALUE
where the '=' and surrounding whitespace is optional.
* The VARIABLE name may contain any character other than whitespace,
'=', or '.', but sticking to 'A-Za-z_' is safest.
* If '.PROGNAME' is present, the definition only applies if the
program that is running is named (i.e., the last component of
'argv[0]' is) PROGNAME or 'PROGNAME.{exe,bat,cmd,...}'. Most
notably, this allows different flavors of TeX to have different
search paths.
* VALUE may contain any characters except '%' and '@'. (These
restrictions are only necessary because of the processing done on
'texmf.cnf' at build time, so you can stick those characters in
after installation if you have to.) The '$VAR.PROG' feature is not
available on the right-hand side; instead, you must use an
additional variable (see below for example). A ';' in VALUE is
translated to ':' if running under Unix; this is useful to write a
single 'texmf.cnf' which can be used under both Unix and Windows.
* All definitions are read before anything is expanded, so you can
use variables before they are defined (like Make, unlike most other
programs).
Here is a configuration file fragment illustrating most of these points:
% TeX input files -- i.e., anything to be found by \input or \openin ...
latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex//
latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex//
TEXINPUTS = .:$TEXMF/tex//
TEXINPUTS.latex209 = $latex209_inputs
TEXINPUTS.latex2e = $latex2e_inputs
TEXINPUTS.latex = $latex2e_inputs
This format has obvious similarities to Bourne shell scripts--change
the comment character to '#', disallow spaces around the '=', and get
rid of the '.NAME' convention, and it could be run through the shell.
However, there seemed little advantage in this, since all the
information would have to passed back to Kpathsea and parsed there
anyway, since the 'sh' process couldn't affect its parent's environment.
The implementation of all this is in 'kpathsea/cnf.c'.