TeX's way of finding files is quite rich and complicated and at certain points
counterintuitive. I am going to explain this at the hand of an example:
finding a .sty file. I am going to explain this, using the setup I ship as
reference.

1. Environment variables:

TeX finds files using certain environment variables that set the paths and
directories where to look. Normally, these variables are *not* set in the
environment, but they are read from a special configuration file, called
texmf.cnf. The standard texmf.cnf is located here:

	/usr/local/teTeX/share/texmf/web2c/texmf.cnf

And settings in that file should not be changed (as you lose those changes
when you update teTeX). Instead, I override several settings in the following
file:

	/usr/local/teTeX/texmf.cnf

2. TEXINPUTS

When TeX is called as 'latex' and it wants to read a LATeX .sty file, it
prefers the path in the environment variable "TEXINPUTS.latex". When TeX is
called as 'pdflatex' and it wants to read a LATeX .sty file, it prefers the
path in the environment variable "TEXINPUTS.pdflatex". Etc. We take latex as
our example. TEXINPUTS.latex is defined as:

	TEXINPUTS.latex = .:$TEXMF/tex/{latex,generic,}//

What this means is that TeX will first look in the current directory ("."),
after which it will look in "$TEXMF/tex/{latex,generic,}//". The {} part is
expanded first, so the above will expand to:

	$TEXMF/tex/latex//,$TEXMF/tex/generic//,$TEXMF/tex///

$TEXMF is the location of the TEXMF trees' These trees contain far more than
just .sty files. They may contain fonts, bibliography files etc. As you can
see in the last expansion, TeX looks for .sty files only in the "texmf"
subtree of the TEXMF trees, and then (again: when called as latex) first in
the "latex" subsubtree, then the "generic" subsubtree and finally in the
entire "tex" subtree.

In /usr/local/teTeX/texmf.cnf, TEXMF could be defined (in fact it differs but
I want to keep it simpler here for explanation purposes) as:

	TEXMF={$HOMETEXMF,!!$TEXMFLOCAL,!!$TEXMFTE,!!$TEXMFMAIN}

in other words, TeX looks in four different locations for a texmf tree. We
will forget about the meaning of !! for the moment, and we will expand
TEXINPUTS.latex further:

	$HOMETEXMF/tex/latex//,$TEXMFLOCAL/tex/latex//,
		$TEXMFTE/tex/latex//,$TEXMFMAIN/tex/latex//,
	$HOMETEXMF/tex/generic//,$TEXMFLOCAL/tex/generic//,
		$TEXMFTE/tex/generic//,$TEXMFMAIN/tex/generic//,
	$HOMETEXMF/tex///,$TEXMFLOCAL/tex///,$TEXMFTE/tex///,$TEXMFMAIN/tex///

Or: first TeX looks in all the "latex" subsubtrees, then in all the "generic"
subsubtrees and finally it looks in all the "tex" subtrees. This is
counterintuitive in that the global "latex" subsubtree is searched *before*
the entire HOMETEXMF tree is searched. The web2c designers have decided that
file 'type/class' is more important than search path, but for some programs,
it is not the file type, but the program that matters because for certain
types of files the extensions are not limited to a known set, like people
creating LATeX files as .ltx files (confused? I don't blame you: I am confused
as well).

We are not home free yet. $HOMETEXMF is simple, it just points to a texmf tree
you can create in your own home directory in the following location:

	HOMETEXMF=$HOME/Library/texmf

where $HOME is your home directory. The other three ($TEXMFLOCAL, $TEXMFTE and
$TEXMFMAIN) are more complicated. I will take only $TEXMFLOCAL as an example.

	TEXMFLOCAL = $SELFAUTOPARENT/share/texmf.local

$SELFAUTOPARENT is set dynamically, depending on the location of your binary.
TeX therefore can sort-of dynamically locate your texmf trees. In our case, it
will expand to /usr/local/teTeX/share/texmf.local.

The result of all these expansions can be shown with the help of the program
"kpsewhich". Since, KPSE (the path search engine in TeX) doesn't know about
".sty" files per se (as it does about - say - ".bib" files) we ask it how it
would try to find a ".tex" file when it is called as "latex" (formatted for
your convenience):

	kpsewhich -progname=latex -show-path=.tex

	.:
	/Users/gerben/Library/texmf/tex/latex//:
	!!/usr/local/teTeX/share/texmf.local/tex/latex//:
	!!/usr/local/teTeX/share/texmf.tetex/tex/latex//:
	!!/usr/local/teTeX/share/texmf/tex/latex//:
	/Users/gerben/Library/texmf/tex/generic//:
	!!/usr/local/teTeX/share/texmf.local/tex/generic//:
	!!/usr/local/teTeX/share/texmf.tetex/tex/generic//:
	!!/usr/local/teTeX/share/texmf/tex/generic//:
	/Users/gerben/Library/texmf/tex///:
	!!/usr/local/teTeX/share/texmf.local/tex///:
	!!/usr/local/teTeX/share/texmf.tetex/tex///:
	!!/usr/local/teTeX/share/texmf/tex///

3. texhash!!

So, what about "!!"? Well, texmf trees can be pretty big and finding a file
takes a lot of time in those big trees. For this speed problem there is a
solution: hash files that live in the top of the tree and that contain
information to locate files fast. These files are named "ls-R".

When a path entry begins with a "!!", TeX will *only* look in the "ls-lR" file
and not in the directory tree. When the contents of your tree change, you need
to run the "texhash" command from the command line. TeX's own file generating
commands (like the commands to create pk files) will add the files they create
to an existing "ls-R", so you need not worry about TeX itself.

In the example above, you can see that texmf, texmf.tetex and texmf.local have an
"ls-R" hash file. These trees are not writable for the ordinary user and when
something is changed in them it is done by the local administrator who has the
privileges to write the "ls-R" hash files. The files in my user directory are
searched without an "ls-R" hash file (unless such a file is available, but in
that case: remove it immediately, it generally only makes life worse for you).

Gerben Wierda
