Contents:

  Reporting bugs
    Bug checklist
    Mailing lists
    Debugging
    Logging
    Common problems
      Unable to find files
      Slow path searching
      Unable to generate fonts
      TeX or Metafont failing
      `XtStrings'
      `dlopen'
      `ShellWidgetClass'
      Pointer combination warnings


Reporting 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, ...

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.

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

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.  Also, 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.

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

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.

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

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

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, `MakeTeXPK' (or
     `MakeTeXMF' or `MakeTeXTFM') 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
     `MakeTeXPK'; 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::.

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

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

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

  If `mf' is a command not found by `MakeTeXPK', 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
`MakeTeXPK' 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.

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; *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.

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

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

`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, *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'.

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.