Man Pages

mktex - phpMan mktex - phpMan

Command: man perldoc info search(apropos)  


File: kpathsea.info,  Node: Filename database,  Next: Invoking kpsewhich,  Prev: Path expansion,  Up: Path searching

3.4 Filename database (`ls-R')
==============================

Kpathsea goes to some lengths to minimize disk accesses for searches
(*note Subdirectory expansion::).  Nevertheless, at installations with
enough directories, searching each possible directory for a given file
can take an excessively long time (depending on the speed of the disk,
whether it's NFS-mounted, how patient you are, etc.).

   In practice, a font tree containing the standard PostScript and PCL
fonts is large enough for searching to be noticeably slow on typical
systems these days.  Therefore, Kpathsea can use an externally-built
"database" file named `ls-R' that maps files to directories, thus
avoiding the need to exhaustively search the disk.

   A second database file `aliases' allows you to give additional names
to the files listed in `ls-R'.  This can be helpful to adapt to "8.3"
filename conventions in source files.

   The `ls-R' and `aliases' features are implemented in the source file
`kpathsea/db.c'.

* Menu:

* ls-R::                        The main filename database.
* Filename aliases::            Aliases for those names.
* Database format::             Syntax details of the database file.

File: kpathsea.info,  Node: ls-R,  Next: Filename aliases,  Up: Filename database

3.4.1 `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.

File: kpathsea.info,  Node: Filename aliases,  Next: Database format,  Prev: ls-R,  Up: Filename database

3.4.2 Filename aliases
----------------------

In some circumstances, you may wish to find a file under several names.
For example, suppose a TeX document was created using a DOS system and
tries to read `longtabl.sty'.  But now it's being run on a Unix system,
and the file has its original name, `longtable.sty'.  The file won't be
found.  You need to give the actual file `longtable.sty' an alias
`longtabl.sty'.

   You can handle this by creating a file `aliases' as a companion to
the `ls-R' for the hierarchy containing the file in question.  (You
must have an `ls-R' for the alias feature to work.)

   The format of `aliases' is simple: two whitespace-separated words
per line; the first is the real name `longtable.sty', and second is the
alias (`longtabl.sty').  These must be base filenames, with no
directory components.  `longtable.sty' must be in the sibling `ls-R'.

   Also, blank lines and lines starting with `%' or `#' are ignored in
`aliases', to allow for comments.

   If a real file `longtabl.sty' exists, it is used regardless of any
aliases.

File: kpathsea.info,  Node: Database format,  Prev: Filename aliases,  Up: Filename database

3.4.3 Database format
---------------------

The "database" read by Kpathsea is a line-oriented file of plain text.
The format is that generated by GNU (and most other) `ls' programs
given the `-R' option, as follows.

   * Blank lines are ignored.

   * If a line begins with `/' or `./' or `../' and ends with a colon,
     it's the name of a directory.  (`../' lines aren't useful,
     however, and should not be generated.)

   * All other lines define entries in the most recently seen directory.
     /'s in such lines will produce possibly-strange results.

   * Files with no preceding directory line are ignored.

   For example, here's the first few lines of `ls-R' (which totals
about 30K bytes) on my system:

     bibtex
     dvips
     fonts
     ls-R
     metafont
     metapost
     tex
     web2c

     ./bibtex:
     bib
     bst
     doc

     ./bibtex/bib:
     asi.bib
     btxdoc.bib
     ...