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, similar to 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 will 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 (preceding spaces are ignored), 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. The PROGNAME value
is used literally, without variable or other expansions.
* Considered as strings, VALUE may contain any character. However,
in practice most 'texmf.cnf' values are related to path expansion,
and since various special characters are used in expansion, such as
braces and commas, they cannot be used in directory names.
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, in order
to have a single 'texmf.cnf' that can support both Unix and Windows
systems. This translation happens with any value, not just search
paths, but fortunately in practice ';' is not needed in other
values.
* 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 some similarity 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 combination of spaces being ignored before the '.' of a program
name qualifer and the optional '=' for the assignment has an unexpected
consequence: if the value begins with a literal '.' and the '=' is
omitted, the intended value is interpreted as a program name. For
example, a line 'var .;/some/path' is taken as an empty value for 'var'
running under the program named ';/some/path'. To diagnose this,
Kpathsea warns if the program name contains a path separator or other
special character. The simplest way to avoid the problem is to use the
'='.
Exactly when a character will be considered special or act as itself
depends on the context in which it is used. The rules are inherent in
the multiple levels of interpretation of the configuration (parsing,
expansion, search, ...) and so cannot be concisely stated,
unfortunately. There is no general escape mechanism; in particular, '\'
is not an "escape character" in 'texmf.cnf' files. When it comes
choosing directory names for installation, it is safest to avoid them
all.
The implementation of all this is in 'kpathsea/cnf.c'.
Info Catalog
kpathsea: Path sources