This is Info file kpathsea.info, produced by Makeinfo version 1.68 from
the input file kpathsea.texi.

INFO-DIR-SECTION TeX
START-INFO-DIR-ENTRY
* Kpathsea: (kpathsea).                       File lookup along search paths.
* kpsewhich: (kpathsea)Invoking kpsewhich.    TeX file searching.
* mktexmf: (kpathsea)mktex scripts.           MF source generation.
* mktexpk: (kpathsea)mktex scripts.           PK bitmap generation.
* mktextex: (kpathsea)mktex scripts.          TeX source generation.
* mktextfm: (kpathsea)mktex scripts.          TeX font metric generation.
* mktexlsr: (kpathsea)Filename database.      Update ls-R.
END-INFO-DIR-ENTRY

  This file documents the Kpathsea library for path searching.

  Copyright (C) 1993, 94, 95, 96, 97 K. Berry & O. Weber.

  Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

  Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

  Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: kpathsea.info,  Node: Electronic distribution,  Next: CD-ROM distribution,  Up: unixtex.ftp

Electronic distribution
-----------------------

  In many places we refer to CTAN:.  This is *both* a host name and a
directory name.  Here are some primary locations:

     `ftp://ctan.tug.org/tex-archive'    (California, USA)
     `ftp://ftp.dante.de/tex-archive'    (Germany)
     `ftp://ftp.tex.ac.uk/tex-archive'   (England)

CTAN has many mirrors worldwide; see the top-level file
`README.mirrors' from one of the sites above, or finger
<ctan@ftp.tug.org>, or see `http://www.tug.org/CTAN.sites'.  A list
current as of the time of distribution is in the top-level file
`./MIRROR'.

  You can also access CTAN via the World Wide Web, Gopher, electronic
mail, or NFS.  The same `README.mirrors' file explains how.

  You will need to retrieve some or all of the following archives,
depending on your needs (don't forget to set binary mode for file
transfers):

`CTAN:/systems/web2c/texmflib.tar.gz'
     A basic collection of fonts (TFM files only) and macro packages
     (including Texinfo and LaTeX 2e).  It unpacks into `texmf/'; if
     you change the structure of this hierarchy, you will also have to
     change the default search paths (*note Changing search paths::.).
     It is required unless you already have these files, in which case
     you should change the default paths as necessary to find them.
     There are other packages of library files, `etexlib.tar.gz',
     `omegalib.tar.gz', and `pdftexlib.tar.gz', that are required as
     well if you install e-TeX, Omega, or pdfTeX respectively.

`CTAN:/systems/web2c/web.tar.gz'
     The original WEB source files, written mostly by Don Knuth.
     Required unless you already have this `web' version.  (The WEB
     sources change irregularly with respect to Web2c itself.)  Unpacks
     into `web2c-VERSION'.

`CTAN:/systems/web2c/web2c.tar.gz'
     The Web2c system.  Required.  Also unpacks into `web2c-VERSION'.

`CTAN:/systems/web2c/web2c-etex.tar.gz'
     Additions to the Web2c system for building e-TeX.  Optional.  Also
     unpacks into `web2c-VERSION'.

`CTAN:/systems/web2c/web2c-omega.tar.gz'
     Additions to the Web2c system for building Omega.  Optional.  Also
     unpacks into `web2c-VERSION'.

`CTAN:/systems/web2c/web2c-pdftex.tar.gz'
     Additions to the Web2c system for building pdfTeX.  Optional.  Also
     unpacks into `web2c-VERSION'.

`CTAN:/systems/web2c/texk.tar.gz'
     The web and web2c sources, plus the additions for web2c, plus the
     dvi drivers mentioned below, plus extra dvi drivers and tools not
     packaged separately.  Recommended if you want to build a complete
     system.  Unpacks into `texk-VERSION'.

`CTAN:/dviware/dvipsk/dvipsk.tar.gz'
     DVI-to-PostScript translator.  Unpacks into `dvipsk-VERSION'.
     Optional.

`CTAN:/dviware/xdvik/xdvik.tar.gz'
     X window system DVI previewer.  Unpacks into `xdvik-VERSION'.
     Optional.

`CTAN:/dviware/dviljk/dviljk.tar.gz'
     DVI-to-PCL (HP LaserJet) translator.  Unpacks into
     `dviljk-VERSION'.  Optional.

  All that said, the originating host for the software above is
`ftp.tug.org'.  You can retrieve these distributions (but not much
else) from the `tex/' directory on that host.


File: kpathsea.info,  Node: CD-ROM distribution,  Next: Tape distribution,  Prev: Electronic distribution,  Up: unixtex.ftp

CD-ROM distribution
-------------------

  Numerous organizations distribute various TeX CD-ROM's:

   * TUG, UK TUG, and GUTenberg (French-speaking TeX user group)
     collaborated to produce the `TeX Live' CD-ROM, based on teTeX,
     which in turn is based on Web2c; email <tex-live@mail.tug.org> or
     see `http://www.tug.org/tex-live.html'.

   * Dante (the German-speaking TeX user group) has produced a CD-ROM.
     See `http://www.dante.de/dante/DANTE-CTAN-CD-ROM.html', and
     `http://www.dante.de/tex-informationen/CD-ROMs.html' for
     information about TeX CD's in general.  Both are in German.

   * The Free Software Foundation's `Source Code CD-ROM' contains the
     minimal TeX source distribution described in the previous section
     (i.e., enough to print GNU documentation); email
     <gnu@prep.ai.mit.edu>.

   * The Gateway! CD-ROM set contains a runnable NetBSD/Amiga
     distribution and sources; see
     `http://www.netbsd.org/Sites/cdroms.html'.

   * The InfoMagic CD-ROM is a copy of CTAN (see previous section); see
     `http://www.infomagic.com'.

   * NTG (Dutch-speaking TeX user group) produced the 4allTeX CD-ROM;
     email <ntg@nic.surfnet.nl>, or see `http://www.ntg.nl/4allcd/'.
     This is a runnable system.

   * The Prime Time TeXcetera CD-ROM is also a copy of CTAN; email
     <ptf@ctcl.com> or see `http://www.ptf.com/ptf/'.

   * Walnut Creek's TeX CD-ROM is also a copy of CTAN; email
     <info@cdrom.com> or see `http://www.cdrom.com:/titles/tex.html'.

   * Most Linux distributions include some TeX package based on Web2c;
     see the Linux documentation file `Distribution-HOWTO' for a
     comparison of Linux distributions, available (for example) via
     `http://www.linux.org'.

  If you know of additional TeX CD-ROM distributions to add to this
list, please inform <kb@mail.tug.org>.


File: kpathsea.info,  Node: Tape distribution,  Next: Other TeX packages,  Prev: CD-ROM distribution,  Up: unixtex.ftp

Tape distribution
-----------------

  You can obtain a complete TeX distribution, including Web2c, on tape.
Contact:
     Pierre MacKay / Denny Hall, Mail Stop DH-10 / Department of Classics
     University of Washington / Seattle, WA 98195 / USA
     phone: 206-543-2268; email: <unixtex@u.washington.edu>

  At this writing, the distribution is available in `tar' format on 1/4
inch 4-track QIC-24 cartridges and 4mm DAT cartridges, and the cost is
US$210.  Make checks payable to the University of Washington, drawn on
a U.S. bank.  Purchase orders are acceptable, but they carry an extra
charge of $10 to pay for invoice processing.  Overseas sites, please
add $20 for shipment via air parcel post, or $30 for shipment via
courier.


File: kpathsea.info,  Node: Other TeX packages,  Prev: Tape distribution,  Up: unixtex.ftp

Other TeX packages
------------------

  Many other TeX implementations are available in `CTAN:/systems',
including ready-to-run distributions for Unix, Amiga, Acorn, VMS,
Macintosh, DOS, and Windows (in various forms).  Although Web2c has
support in the source code for many operating systems, and in fact some
of the other distributions are based on it, it's unlikely to work as
distributed on anything but Unix.  (Please contribute improvements!)

  The Unix distribution alluded to above is the teTeX distribution.
This includes both complete sources and precompiled binaries for many
popular Unix variants, including Linux. It is based on Web2c, and
contains many other TeX-related programs as well.

  The host labrea.stanford.edu is the original source for the files for
which Donald Knuth is directly responsible: `tex.web', `plain.tex',
etc. However, unless you want to build your TeX library tree ab initio,
it is more reliable and less work to retrieve these files as part of
the above packages. In any case, labrea is not the canonical source for
anything except what was created by Stanford TeX project, so do not
rely on all the files available at that ftp site being up-to-date.


File: kpathsea.info,  Node: Reporting bugs,  Prev: unixtex.ftp,  Up: Installation

Reporting bugs
==============

  (A copy of this chapter is in the file `kpathsea/BUGS'.)

  If you have problems or suggestions, please report them to
<tex-k@mail.tug.org> using the bug checklist below.

  Please report bugs in the documentation; not only factual errors or
inconsistent behavior, but unclear or incomplete explanations, typos,
wrong fonts, ...

* Menu:

* Bug checklist::       What to include in a good bug report.
* Mailing lists::       Joining the bugs or announcements mailing lists.
* Debugging::           Analyzing runtime problems.
* Logging::             Recording searches.
* Common problems::     When things go wrong.


File: kpathsea.info,  Node: Bug checklist,  Next: Mailing lists,  Up: Reporting bugs

Bug checklist
-------------

  Before reporting a bug, please check below to be sure it isn't already
known (*note Common problems::.).

  Bug reports should be sent via electronic mail to
<tex-k@mail.tug.org>, or by postal mail to 135 Center Hill Road /
Plymouth, MA 02360 / USA.

  The general principle is that a good bug report includes all the
information necessary for reproduction.  Therefore, to enable
investigation, your report should include the following:

   * The version number(s) of the program(s) involved, and of Kpathsea
     itself.  You can get the former by giving a sole option `--version'
     to the program, and the latter by running `kpsewhich --version'.
     The `NEWS' and `ChangeLog' files also contain the version number.

   * The hardware, operating system (including version number),
     compiler, and `make' program you are using (the output of `uname
     -a' is a start on the first two, though often incomplete).  If the
     bug involves the X window system, include X version and supplier
     information as well (examples: X11R6 from MIT; X11R4 from HP;
     OpenWindows 3.3 bundled with SunOS 4.1.4).

   * Any options you gave to `configure'.  This is recorded in the
     `config.status' files.

     If you are reporting a bug in `configure' itself, it's probably
     system-dependent, and it will be unlikely the maintainers can do
     anything useful if you merely report that thus-and-such is broken.
     Therefore, you need to do some additional work: for some bugs, you
     can look in the file `config.log' where the test that failed should
     appear, along with the compiler invocation and source program in
     question.  You can then compile it yourself by hand, and discover
     why the test failed.  Other `configure' bugs do not involve the
     compiler; in that case, the only recourse is to inspect the
     `configure' shell script itself, or the Autoconf macros that
     generated `configure'.

   * The log of all debugging output, if the bug is in path searching.
     You can get this by setting the environment variable
     `KPATHSEA_DEBUG' to `-1' before running the program.  Please look
     at the log yourself to make sure the behavior is really a bug
     before reporting it; perhaps "old" environment variable settings
     are causing files not to be found, for example.

   * The contents of any input files necessary to reproduce the bug.
     For bugs in DVI-reading programs, for example, this generally
     means a DVI file (and any EPS or other files it uses)--TeX source
     files are helpful, but the DVI file is necessary, because that's
     the actual program input.

     GNU `shar', available from `ftp://prep.ai.mit.edu/pub/gnu' is a
     convenient way of packaging multiple (possibly binary) files for
     electronic mail.  If you feel your input files are too big to send
     by email, you can ftp them to `ftp://ftp.tug.org/incoming' (that
     directory is writable, but not readable).

   * If you are sending a patch (do so if you can!), please do so in
     the form of a context diff (`diff -c') against the original
     distribution source.  Any other form of diff is either not as
     complete or harder for me to understand.  Please also include a
     `ChangeLog' entry.

   * If the bug involved is an actual crash (i.e., core dump), it is
     easy and useful to include a stack trace from a debugger (I
     recommend the GNU debugger GDB, available from
     `ftp://prep.ai.mit.edu/pub/gnu').  If the cause is apparent (a
     `NULL' value being dereferenced, for example), please send the
     details along.  If the program involved is TeX or Metafont, and
     the crash is happening at apparently-sound code, however, the bug
     may well be in the compiler, rather than in the program or the
     library (*note TeX or Metafont failing: TeX or Metafont failing.).

   * Any additional information that will be helpful in reproducing,
     diagnosing, or fixing the bug.


File: kpathsea.info,  Node: Mailing lists,  Next: Debugging,  Prev: Bug checklist,  Up: Reporting bugs

Mailing lists
-------------

  Web2c and Kpathsea in general are discussed on the mailing list
<tex-k@mail.tug.org>.  To join, email <tex-k-request@mail.tug.org> with
a line consisting of

     subscribe YOU@YOUR.PREFERRED.EMAIL.ADDRESS

in the body of the message.

  You do not need to join to submit a report, nor will it affect whether
you get a response.  There is no Usenet newsgroup equivalent (if you can
be the one to set this up, email `tex-k-request').  Traffic on the list
is fairly light, and is mainly bug reports and enhancement requests to
the software.  The best way to decide if you want to join or not is
read some of the archives from `ftp://ftp.tug.org/mail/archives/tex-k/'.

  Be aware that large data files are sometimes included in bug reports.
If this is a problem for you, do not join the list.

  If you only want announcements of new releases, not bug reports and
discussion, join <tex-archive@math.utah.edu> (via mail to
<tex-archive-request@math.utah.edu>).

  If you are looking for general TeX help, such as how to use LaTeX,
please use the mailing list <info-tex@shsu.edu> mailing list, which is
gatewayed to the `comp.text.tex' Usenet newsgroup (or post to the
newsgroup; the gateway is bidirectional).


File: kpathsea.info,  Node: Debugging,  Next: Logging,  Prev: Mailing lists,  Up: Reporting bugs

Debugging
---------

  Kpathsea provides a number of runtime debugging options, detailed
below by their names and corresponding numeric values.  When the files
you expect aren't being found, the thing to do is enable these options
and examine the output.

  You can set these with some runtime argument (e.g., `-d') to the
program; in that case, you should use the numeric values described in
the program's documentation (which, for Dvipsk and Xdvik, are different
than those below).  It's best to give the `-d' (or whatever) option
first, for maximal output.  Dvipsk and Xdvik have additional
program-specific debugging options as well.

  You can also set the environment variable `KPATHSEA_DEBUG'; in this
case, you should use the numbers below.  If you run the program under a
debugger and set the variable `kpathsea_debug', also use the numbers
below.

  In any case, by far the simplest value to use is `-1', which will
turn on all debugging output.  This is usually better than guessing
which particular values will yield the output you need.

  Debugging output always goes to standard error, so you can redirect it
easily.  For example, in Bourne-compatible shells:
     dvips -d -1 ... 2>/tmp/debug

  It is sometimes helpful to run the standalone Kpsewhich utility
(*note Invoking kpsewhich::.), instead of the original program.

  In any case, you can *not* use the *names* below; you must always use
somebody's numbers.  (Sorry.)  To set more than one option, just sum
the corresponding numbers.

`KPSE_DEBUG_STAT (1)'
     Report `stat'(2) calls. This is useful for verifying that your
     directory structure is not forcing Kpathsea to do many additional
     file tests (*note Slow path searching::., and *note Subdirectory
     expansion::.). If you are using an up-to-date `ls-R' database
     (*note Filename database::.), this should produce no output unless
     a nonexistent file that must exist is searched for.

`KPSE_DEBUG_HASH (2)'
     Report lookups in all hash tables: `ls-R' and `aliases' (*note
     Filename database::.); font aliases (*note Fontmap::.); and config
     file values (*note Config files::.).  Useful when expected values
     are not being found, e.g.., file searches are looking at the disk
     instead of using `ls-R'.

`KPSE_DEBUG_FOPEN (4)'
     Report file openings and closings. Especially useful when your
     system's file table is full, for seeing which files have been
     opened but never closed. In case you want to set breakpoints in a
     debugger: this works by redefining `fopen' (`fclose') to be
     `kpse_fopen_trace' (`kpse_fclose_trace').

`KPSE_DEBUG_PATHS (8)'
     Report general path information for each file type Kpathsea is
     asked to search. This is useful when you are trying to track down
     how a particular path got defined--from `texmf.cnf', `config.ps',
     an environment variable, the compile-time default, etc.  This is
     the contents of the `kpse_format_info_type' structure defined in
     `tex-file.h'.

`KPSE_DEBUG_EXPAND (16)'
     Report the directory list corresponding to each path element
     Kpathsea searches. This is only relevant when Kpathsea searches
     the disk, since `ls-R' searches don't look through directory lists
     in this way.

`KPSE_DEBUG_SEARCH (32)'
     Report on each file search: the name of the file searched for, the
     path searched in, whether or not the file must exist (when drivers
     search for `cmr10.vf', it need not exist), and whether or not we
     are collecting all occurrences of the file in the path (as with,
     e.g., `texmf.cnf' and `texfonts.map'), or just the first (as with
     most lookups).  This can help you correlate what Kpathsea is doing
     with what is in your input file.

`KPSE_DEBUG_VARS (64)'
     Report the value of each variable Kpathsea looks up.  This is
     useful for verifying that variables do indeed obtain their correct
     values.

`GSFTOPK_DEBUG (128)'
     Activates debugging printout specific to `gsftopk' program.

`MAKETEX_DEBUG (512)'
     If you use the optional `mktex' programs instead of the
     traditional shell scripts, this will report the name of the site
     file (`mktex.cnf' by default) which is read, directories created by
     `mktexdir', the full path of the `ls-R' database built by
     `mktexlsr', font map searches, `MT_FEATURES' in effect, parameters
     from `mktexnam', filenames added by `mktexupd', and some
     subsidiary commands run by the programs.

`MAKETEX_FINE_DEBUG (1024)'
     When the optional `mktex' programs are used, this will print
     additional debugging info from functions internal to these
     programs.

  Debugging output from Kpathsea is always written to standard error,
and begins with the string `kdebug:'. (Except for hash table buckets,
which just start with the number, but you can only get that output
running under a debugger. See comments at the `hash_summary_only'
variable in `kpathsea/db.c'.)


File: kpathsea.info,  Node: Logging,  Next: Common problems,  Prev: Debugging,  Up: Reporting bugs

Logging
-------

  Kpathsea can record the time and filename found for each successful
search.  This may be useful in finding good candidates for deletion when
your filesystem is full, or in discovering usage patterns at your site.

  To do this, define the environment or config file variable
`TEXMFLOG'.  The value is the name of the file to append the
information to.  The file is created if it doesn't exist, and appended
to if it does.

  Each successful search turns into one line in the log file: two words
separated by a space. The first word is the time of the search, as the
integer number of seconds since "the epoch", i.e., UTC midnight 1
January 1970 (more precisely, the result of the `time' system call).
The second word is the filename.

  For example, after `setenv TEXMFLOG /tmp/log', running Dvips on
`story.dvi' appends the following lines:

     774455887 /usr/local/share/texmf/dvips/config.ps
     774455887 /usr/local/share/texmf/dvips/psfonts.map
     774455888 /usr/local/share/texmf/dvips/texc.pro
     774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk
     774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk
     774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
     774455889 /usr/local/share/texmf/dvips/texc.pro

Only filenames that are absolute are recorded, to preserve some
semblance of privacy.


File: kpathsea.info,  Node: Common problems,  Prev: Logging,  Up: Reporting bugs

Common problems
---------------

  Here are some common problems with configuration, compilation,
linking, execution, ...

* Menu:

* Unable to find files::        If your program can't find fonts (or whatever).
* Slow path searching::         If it takes forever to find anything.
* Unable to generate fonts::    If mktexpk fails.
* TeX or Metafont failing::     Likely compiler bugs.

* Empty Makefiles::            	When configure produces empty makefiles.
* XtStrings::                   When _XtStrings is undefined.
* dlopen::                      When dlopen is undefined.
* ShellWidgetClass::            For dynamic linking troubles under OpenWindows.
* Pointer combination warnings::  For old compilers that don't grok char *.


File: kpathsea.info,  Node: Unable to find files,  Next: Slow path searching,  Up: Common problems

Unable to find files
....................

  If a program complains it cannot find fonts (or other input files),
any of several things might be wrong.  In any case, you may find the
debugging options helpful.  *Note Debugging::.

   * Perhaps you simply haven't installed all the necessary files; the
     basic fonts and input files are distributed separately from the
     programs.  *Note unixtex.ftp::.

   * You have (perhaps unknowingly) told Kpathsea to use search paths
     that don't reflect where the files actually are.  One common cause
     is having environment variables set from a previous installation,
     thus overriding what you carefully set in `texmf.cnf' (*note
     Supported file formats::.).  System `/etc/profile' or other files
     such may be the culprit.

   * Your files reside in a directory that is only pointed to via a
     symbolic link, in a leaf directory and is not listed in `ls-R'.

     Unfortunately, Kpathsea's subdirectory searching has an
     irremediable deficiency: If a directory D being searched for
     subdirectories contains plain files and symbolic links to other
     directories, but no true subdirectories, D will be considered a
     leaf directory, i.e., the symbolic links will not be followed.
     *Note Subdirectory expansion::.

     You can work around this problem by creating an empty dummy
     subdirectory in D. Then D will no longer be a leaf, and the
     symlinks will be followed.

     The directory immediately followed by the `//' in the path
     specification, however, is always searched for subdirectories,
     even if it is a leaf.  Presumably you would not have asked for the
     directory to be searched for subdirectories if you didn't want it
     to be.

   * If the fonts (or whatever) don't already exist, `mktexpk' (or
     `mktexmf' or `mktextfm') will try to create them.  If these rather
     complicated shell scripts fail, you'll eventually get an error
     message saying something like `Can't find font FONTNAME'. The best
     solution is to fix (or at least report) the bug in `mktexpk'; the
     workaround is to generate the necessary fonts by hand with
     Metafont, or to grab them from a CTAN site (*note unixtex.ftp::.).

   * There is a bug in the library. *Note Reporting bugs::.


File: kpathsea.info,  Node: Slow path searching,  Next: Unable to generate fonts,  Prev: Unable to find files,  Up: Common problems

Slow path searching
...................

  If your program takes an excessively long time to find fonts or other
input files, but does eventually succeed, here are some possible
culprits:

   * Most likely, you just have a lot of directories to search, and that
     takes a noticeable time. The solution is to create and maintain a
     separate `ls-R' file that lists all the files in your main TeX
     hierarchy.  *Note Filename database::.  Kpathsea always uses `ls-R'
     if it's present; there's no need to recompile or reconfigure any
     of the programs.

   * Your recursively-searched directories (e.g.,
     `/usr/local/share/texmf/fonts//'), contain a mixture of files and
     directories. This prevents Kpathsea from using a useful
     optimization (*note Subdirectory expansion::.).

     It is best to have only directories (and perhaps a `README') in the
     upper levels of the directory structure, and it's very important
     to have *only* files, and no subdirectories, in the leaf
     directories where the dozens of TFM, PK, or whatever files reside.

  In any case, you may find the debugging options helpful in determining
precisely when the disk or network is being pounded.  *Note Debugging::.


File: kpathsea.info,  Node: Unable to generate fonts,  Next: TeX or Metafont failing,  Prev: Slow path searching,  Up: Common problems

Unable to generate fonts
........................

  This can happen if either `mktexpk' hasn't been installed properly,
or if the local installation of Metafont isn't correct.

  If `mf' is a command not found by `mktexpk', then you need to install
Metafont (*note unixtex.ftp::.).

  If Metafont runs, but generates fonts at the wrong resolution, you
need to be sure the `M' and `D' lines in your Dvips configuration file
match (*note Config files: (dvips)Config files.).  For example, if
`mktexpk' is generating 300dpi fonts, but you need 600dpi fonts, you
should have:
     M ljfour
     D 600

  If Metafont runs but generates fonts at a resolution of 2602dpi (and
prints out the name of each character as well as just a character
number, and maybe tries to display the characters), then your Metafont
base file probably hasn't been made properly.  (It's using the default
`proof' mode, instead of an actual device mode.)  To make a proper
`plain.base', assuming the local mode definitions are contained in a
file `modes.mf', run the following command (assuming Unix):

     inimf "plain; input modes; dump"

Then copy the `plain.base' file from the current directory to where the
base files are stored on your system (`/usr/local/share/texmf/web2c' by
default), and make a link (either hard or soft) from `plain.base' to
`mf.base' in that directory.  *Note inimf invocation: (web2c)inimf
invocation.


File: kpathsea.info,  Node: TeX or Metafont failing,  Next: Empty Makefiles,  Prev: Unable to generate fonts,  Up: Common problems

TeX or Metafont failing
.......................

  If TeX or Metafont get a segmentation fault or otherwise fail while
running a normal input file, the problem is usually a compiler bug
(unlikely as that may sound).  Even if the trip and trap tests are
passed, problems may lurk.  Optimization occasionally causes trouble in
programs other than TeX and Metafont themselves, too.

  Insufficient swap space may also cause core dumps or other erratic
behavior.

  For a workaround, if you enabled any optimization flags, it's best to
omit optimization entirely.  In any case, the way to find the facts is
to run the program under the debugger and see where it's failing.

  Also, if you have trouble with a system C compiler, I advise trying
the GNU C compiler. And vice versa, unfortunately; but in that case I
also recommend reporting a bug to the GCC mailing list; see *Note Bugs:
(gcc)Bugs.

  To report compiler bugs effectively requires perseverance and
perspicacity: you must find the miscompiled line, and that usually
involves delving backwards in time from the point of error, checking
through TeX's (or whatever program's) data structures.  Things are not
helped by all-too-common bugs in the debugger itself.  Good luck.

  One known cause of trouble is the way arrays are handled.  Some of the
Pascal arrays have a lower index other than 0, and the C code will take
the pointer to the allocated memory, subtract the lower index, and use
the resulting pointer for the array.  While this trick often works, ANSI
C doesn't guarantee that it will.  It it known to fail on HP-UX 10
mchines when the native compiler is used, unless the `+u' compiler
switch was specified.  Using GCC will work on this platform as well.


File: kpathsea.info,  Node: Empty Makefiles,  Next: XtStrings,  Prev: TeX or Metafont failing,  Up: Common problems

Empty Makefiles
...............

  On some systems (NetBSD, FreeBSD, AIX 4.1, and Mach10), `configure'
may fail to properly create the Makefiles. Instead, you get an error
which looks something like this:

     prompt$ ./configure
     ...
     creating Makefile
     sed: 1: "\\@^ac_include make/pat ...": \ can not be used as a string delimiter

  So far as I know, the bug here is in `/bin/sh' on these systems. I
don't have access to a machine running any of them, so if someone can
find a workaround that avoids the quoting bug, I'd be most grateful.
(Search for `ac_include' in the `configure' script to get to the
problematic code.)

  It should work to run `bash configure', instead of using `/bin/sh'.
You can get Bash from `ftp://prep.ai.mit.edu/pub/gnu' and mirrors.

  Another possible cause (reported for NeXT) is a bug in the `sed'
command.  In that case the error may look like this:

     Unrecognized command: \@^ac_include make/paths.make@r make/paths.make

  In this case, installing GNU `sed' should solve the problem.  You can
get GNU `sed' from the same places as Bash.


File: kpathsea.info,  Node: XtStrings,  Next: dlopen,  Prev: Empty Makefiles,  Up: Common problems

`XtStrings'
...........

  You may find that linking X programs results in an error from the
linker that `XtStrings' is undefined, something like this:

     gcc -o virmf ...
     .../x11.c:130: undefined reference to `XtStrings'

  This generally happens because of a mismatch between the X include
files with which you compiled and the X libraries with which you linked;
often, the include files are from MIT and the libraries from Sun.

  The solution is to use the same X distribution for compilation and
linking.  Probably `configure' was unable to guess the proper
directories from your installation.  You can use the `configure'
options `--x-includes=PATH' and `--x-libraries=PATH' to explicitly
specify them.


File: kpathsea.info,  Node: dlopen,  Next: ShellWidgetClass,  Prev: XtStrings,  Up: Common problems

`dlopen'
........

  (This section adapted from the file `dlsym.c' in the X distribution.)

  The `Xlib' library uses the standard C function `wcstombs'.  Under
SunOS 4.1, `wcstombs' uses the `dlsym' interface defined in `libdl.so'.
Unfortunately, the SunOS 4.1 distribution does not include a static
`libdl.a' library.

  As a result, if you try to link an X program statically under SunOS,
you may get undefined references to `dlopen', `dlsym', and `dlclose'.
One workaround is to include these definitions when you link:

     void *dlopen() { return 0; }
     void *dlsym()  { return 0; }
     int dlclose()  { return -1; }

These are contained in the `dlsym.c' file in the MIT X distribution.


File: kpathsea.info,  Node: ShellWidgetClass,  Next: Pointer combination warnings,  Prev: dlopen,  Up: Common problems

`ShellWidgetClass'
..................

  (This section adapted from the comp.sys.sun.admin FAQ.)

  If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x,
you may get undefined symbols `_get_wmShellWidgetClass' and
`_get_applicationShellWidgetClass' when linking. This problem does not
arise using the standard MIT X libraries under SunOS.

  The cause is bugs in the `Xmu' shared library as shipped from Sun.
There are several fixes:

   * Install the free MIT distribution from `ftp.x.org' and mirrors.

   * Get the OpenWindows patches listed below.

   * Statically link the `Xmu' library into the executable.

   * Avoid using `Xmu' at all. If you are compiling Metafont, see *Note
     Online Metafont graphics: (web2c)Online Metafont graphics. If you
     are compiling Xdvi, see the `-DNOTOOL' option in `xdvik/INSTALL'.

   * Ignore the errors. The binary runs fine regardless.

  Here is the information for getting the two patches:

     Patch ID: 100512-02
     Bug ID's: 1086793, 1086912, 1074766
     Description: 4.1.x OpenWindows 3.0 `libXt' jumbo patch
     
     Patch ID: 100573-03
     Bug ID: 1087332
     Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared `libXmu'.

  The way to statically link with `libXmu' depends on whether you are
using a Sun compiler (e.g., `cc') or `gcc'. If the latter, alter the
`x_libs' Make variable to include

     -static -lXmu -dynamic

  If you are using the Sun compiler, use `-Bstatic' and `-Bdynamic'.


File: kpathsea.info,  Node: Pointer combination warnings,  Prev: ShellWidgetClass,  Up: Common problems

Pointer combination warnings
............................

  When compiling with old C compilers, you may get some warnings about
"illegal pointer combinations".  These are spurious; just ignore them.
I decline to clutter up the source with casts to get rid of them.


File: kpathsea.info,  Node: Path searching,  Next: TeX support,  Prev: Installation,  Up: Top

Path searching
**************

  This chapter describes the generic path searching mechanism Kpathsea
provides.  For information about searching for particular file types
(e.g., TeX fonts), see the next chapter.

* Menu:

* Searching overview::          Basic scheme for searching.
* Path sources::                Where search paths can be defined.
* Path expansion::              Special constructs in search paths.
* Filename database::           Using an externally-built list to search.
* Invoking kpsewhich::          Standalone path lookup.


File: kpathsea.info,  Node: Searching overview,  Next: Path sources,  Up: Path searching

Searching overview
==================

  A "search path" is a colon-separated list of "path elements", which
are directory names with a few extra frills.  A search path can come
from (a combination of) many sources; see below.  To look up a file
`foo' along a path `.:/dir', Kpathsea checks each element of the path
in turn: first `./foo', then `/dir/foo', returning the first match (or
possibly all matches).

  The "colon" and "slash" mentioned here aren't necessarily `:' and `/'
on non-Unix systems.  Kpathsea tries to adapt to other operating
systems' conventions.

  To check a particular path element E, Kpathsea first sees if a
prebuilt database (*note Filename database::.) applies to E, i.e., if
the database is in a directory that is a prefix of E.  If so, the path
specification is matched against the contents of the database.

  If the database does not exist, or does not apply to this path
element, or contains no matches, the filesystem is searched (if this
was not forbidden by the specification with `!!' and if the file being
searched for must exist).  Kpathsea constructs the list of directories
that correspond to this path element, and then checks in each for the
file being searched for.  (To help speed future lookups of files in the
same directory, the directory in which a file is found is floated to the
top of the directory list.)

  The "file must exist" condition comes into play with VF files and
input files read by the TeX `\openin' command.  These files may not
exist (consider `cmr10.vf'), and so it would be wrong to search the
disk for them.  Therefore, if you fail to update `ls-R' when you
install a new VF file, it will never be found.

  Each path element is checked in turn: first the database, then the
disk.  If a match is found, the search stops and the result is
returned.  This avoids possibly-expensive processing of path
specifications that are never needed on a particular run.  (Unless the
search explicitly requested all matches.)

  Although the simplest and most common path element is a directory
name, Kpathsea supports additional features in search paths: layered
default values, environment variable names, config file values, users'
home directories, and recursive subdirectory searching.  Thus, we say
that Kpathsea "expands" a path element, meaning transforming all the
magic specifications into the basic directory name or names.  This
process is described in the sections below.  It happens in the same
order as the sections.

  Exception to all of the above: If the filename being searched for is
absolute or explicitly relative, i.e., starts with `/' or `./' or
`../', Kpathsea simply checks if that file exists.

  Ordinarily, if Kpathsea tries to access a file or directory that
cannot be read, it gives a warning.  This is so you will be alerted to
directories or files that accidentally lack read permission (for
example, a `lost+found').  If you prefer not to see these warnings,
include the value `readable' in the `TEX_HUSH' environment variable or
config file value.

  This generic path searching algorithm is implemented in
`kpathsea/pathsearch.c'.  It is employed by a higher-level algorithm
when searching for a file of a particular type (*note File lookup::.,
and *Note Glyph lookup::).


File: kpathsea.info,  Node: Path sources,  Next: Path expansion,  Prev: Searching overview,  Up: Path searching

Path sources
============

  A search path can come from many sources.  In the order in which
Kpathsea uses them:

  1. A user-set environment variable, e.g., `TEXINPUTS'.  Environment
     variables with an underscore and the program name appended
     override; for example, `TEXINPUTS_latex' overrides `TEXINPUTS' if
     the program being run is named `latex'.

  2. A program-specific configuration file, e.g., an `S /a:/b' line in
     Dvips' `config.ps' (*note Config files: (dvips)Config files.).

  3. A line in a Kpathsea configuration file `texmf.cnf', e.g.,
     `TEXINPUTS=/c:/d' (see below).

  4. The compile-time default (specified in `kpathsea/paths.h').

  You can see each of these values for a given search path by using the
debugging options (*note Debugging::.).

  These sources may be combined via default expansion (*note Default
expansion::.).

* Menu:

* Config files::        Kpathsea's runtime config files (texmf.cnf).


File: kpathsea.info,  Node: Config files,  Up: Path sources

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'.

  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 `%' and continue to the end of the line.

   * 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'.  This allows different
     flavors of TeX to have different search paths, for example.

   * 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 NT.  (If
     you really want `;''s in your filenames, add
     `-DALLOW_SEMICOLON_IN_FILENAMES' to `CFLAGS'.)

   * 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

  Although 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.  But there seemed little advantage to doing 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'.


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

Path expansion
==============

  Kpathsea recognizes certain special characters and constructions in
search paths, similar to that in shells.  As a general example:
`~$USER/{foo,bar}//baz' expands to all subdirectories under directories
`foo' and `bar' in $USER's home directory that contain a directory or
file `baz'.  These expansions are explained in the sections below.

* Menu:

* Default expansion::           a: or :a or a::b expands to a default.
* Variable expansion::          $foo and ${foo} expand to environment values.
* Tilde expansion::             ~ and ~user expand to home directories.
* Brace expansion::             a{foo,bar}b expands to afoob abarb.
* KPSE_DOT expansion::          . is replaced with $KPSE_DOT if it is defined.
* Subdirectory expansion::      a// and a//b recursively expand to subdirs.


File: kpathsea.info,  Node: Default expansion,  Next: Variable expansion,  Up: Path expansion

Default expansion
-----------------

  If the highest-priority search path (*note Path sources::.) contains
an "extra colon" (i.e., leading, trailing, or doubled), Kpathsea
inserts at that point the next-highest-priority search path that is
defined.  If that inserted path has an extra colon, the same happens
with the next-highest.  (An extra colon in the compile-time default
value has unpredictable results, so installers beware.)

  For example, given an environment variable setting

     setenv TEXINPUTS /home/karl:

and a `TEXINPUTS' value from `texmf.cnf' of

     .:$TEXMF//tex

then the final value used for searching will be:

     /home/karl:.:$TEXMF//tex

  Since Kpathsea looks for multiple configuration files, it would be
natural to expect that (for example) an extra colon in `./texmf.cnf'
would expand to the path in `$TEXMF/texmf.cnf'.  Or, with Dvips'
configuration files, that an extra colon in `config.$PRINTER' would
expand to the path in `config.ps'.  This doesn't happen.  It's not
clear this would be desirable in all cases, and trying to devise a way
to specify the path to which the extra colon should expand seemed truly
baroque.

  Technicality: Since it would be useless to insert the default value in
more than one place, Kpathsea changes only one extra `:' and leaves any
others in place (they will eventually be ignored).  Kpathsea checks
first for a leading `:', then a trailing `:', then a doubled `:'.

  You can trace this by debugging "paths" (*note Debugging::.).
Default expansion is implemented in the source file
`kpathsea/kdefault.c'.


File: kpathsea.info,  Node: Variable expansion,  Next: Tilde expansion,  Prev: Default expansion,  Up: Path expansion

Variable expansion
------------------

  `$foo' or `${foo}' in a path element is replaced by (1) the value of
an environment variable `foo' (if defined); (2) the value of `foo' from
`texmf.cnf' (if defined); (3) the empty string.

  If the character after the `$' is alphanumeric or `_', the variable
name consists of all consecutive such characters. If the character
after the `$' is a `{', the variable name consists of everything up to
the next `}' (braces may not be nested around variable names).
Otherwise, Kpathsea gives a warning and ignores the `$' and its
following character.

  You must quote the $'s and braces as necessary for your shell.
*Shell* variable values cannot be seen by Kpathsea, i.e., ones defined
by `set' in C shells and without `export' in Bourne shells.

  For example, given
     setenv tex /home/texmf
     setenv TEXINPUTS .:$tex:${tex}prev
   the final `TEXINPUTS' path is the three directories:
     .:/home/texmf:/home/texmfprev

  The `.PROGNAME' suffix on variables and `_PROGNAME' on environment
variable names are not implemented for general variable expansions.
These are only recognized when search paths are initialized (*note Path
sources::.).

  Variable expansion is implemented in the source file
`kpathsea/variable.c'.


File: kpathsea.info,  Node: Tilde expansion,  Next: Brace expansion,  Prev: Variable expansion,  Up: Path expansion

Tilde expansion
---------------

  A leading `~' in a path element is replaced by the value of the
environment variable `HOME', or `.' if `HOME' is not set.

  A leading `~USER' in a path element is replaced by USER's home
directory from the system `passwd' database.

  For example,
     setenv TEXINPUTS ~/mymacros:

will prepend a directory `mymacros' in your home directory to the
default path.

  As a special case, if a home directory ends in `/', the trailing
slash is dropped, to avoid inadvertently creating a `//' construct in
the path.  For example, if the home directory of the user `root' is
`/', the path element `~root/mymacros' expands to just `/mymacros', not
`//mymacros'.

  Tilde expansion is implemented in the source file `kpathsea/tilde.c'.


File: kpathsea.info,  Node: Brace expansion,  Next: KPSE_DOT expansion,  Prev: Tilde expansion,  Up: Path expansion

Brace expansion
---------------

  `x{A:B}y' expands to `xAy:xBy'.  For example:

     foo/{1:2}/baz

expands to `foo/1/baz:foo/2/baz'.  `:' is the path separator on the
current system; e.g., on a DOS system, it's `;'.

  Braces can be nested; for example, `x{A:B{1:2}}y' expands to
`xAy:xB1y:xB2y'.

  Multiple non-nested braces are expanded from right to left; for
example, `x{A:B}{1:2}y' expands to `x{A:B}1y:x{A:B}2y', which expands
to `xA1y:xB1y:xA2y:xB2:y'.

  This feature can be used to implement multiple TeX hierarchies, by
assigning a brace list to `$TEXMF', as mentioned in `texmf.in'.

  In old versions of the library you had to use a comma.  While this
usage is deprecated, it is still supported for backwards compatibility
with old configurations.  The last example could have been written
`x{A,B}{1,2}y'.

  Brace expansion is implemented in the source file
`kpathsea/expand.c'.  It is a modification of the Bash sources, and is
thus covered by the GNU General Public License, rather than the Library
General Public License that covers the rest of Kpathsea.


File: kpathsea.info,  Node: KPSE_DOT expansion,  Next: Subdirectory expansion,  Prev: Brace expansion,  Up: Path expansion

`KPSE_DOT' expansion
--------------------

  When `KPSE_DOT' is defined in the environment, it names a directory
that should be considered the current directory for the purpose of
looking up files in the search paths.  This feature is needed by the
`mktex...' scripts *Note mktex scripts::, because these change the
working directory.  You should not ever define it yourself.

