GNU Info

(kpathsea.info)ls-R

---

Next: Filename aliases Up: Filename database

---

Enter node , (file) or (file)node

`ls-R'
------

  As mentioned above, you must name the main filename database `ls-R'.
You can put one at the root of each TeX installation hierarchy you wish
to search (`$TEXMF' by default); most sites have only one hierarchy.
Kpathsea looks for `ls-R' files along the `TEXMFDBS' path, so that
should presumably match the list of hierarchies.

  The recommended way to create and maintain `ls-R' is to run the
`mktexlsr' script, which is installed in `$(bindir)' (`/usr/local/bin'
by default).  That script goes to some trouble to follow symbolic links
as necessary, etc.  It's also invoked by the distributed `mktex...'
scripts.

  At its simplest, though, you can build `ls-R' with the command
     cd /YOUR/TEXMF/ROOT && ls -LAR ./ >ls-R

presuming your `ls' produces the right output format (see the section
below).  GNU `ls', for example, outputs in this format.  Also presuming
your `ls' hasn't been aliased in a system file (e.g., `/etc/profile')
to something problematic, e.g., `ls --color=tty'.  In that case, you
will have to disable the alias before generating `ls-R'.  For the
precise definition of the file format, see Note: Database format.

  Regardless of whether you use the supplied script or your own, you
will almost certainly want to invoke it via `cron', so when you make
changes in the installed files (say if you install a new LaTeX
package), `ls-R' will be automatically updated.

  The `-A' option to `ls' includes files beginning with `.' (except for
`.' and `..'), such as the file `.tex' included with the LaTeX tools
package.  (On the other hand, _directories_ whose names begin with `.'
are always ignored.)

  If your system does not support symbolic links, omit the `-L'.

  `ls -LAR /YOUR/TEXMF/ROOT' will also work.  But using `./' avoids
embedding absolute pathnames, so the hierarchy can be easily
transported.  It also avoids possible trouble with automounters or
other network filesystem conventions.

  Kpathsea warns you if it finds an `ls-R' file, but the file does not
contain any usable entries.  The usual culprit is running plain `ls -R'
instead of `ls -LR ./' or `ls -R /YOUR/TEXMF/ROOT'.  Another
possibility is some system directory name starting with a `.' (perhaps
if you are using AFS); Kpathsea ignores everything under such
directories.

  Because the database may be out-of-date for a particular run, if a
file is not found in the database, by default Kpathsea goes ahead and
searches the disk. If a particular path element begins with `!!',
however, _only_ the database will be searched for that element, never
the disk.  If the database does not exist, nothing will be searched.
Because this can surprise users ("I see the font `foo.tfm' when I do an
`ls'; why can't Dvips find it?"), it is not in any of the default
search paths.