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 (see 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 (see 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.  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 (see 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 (see Slow path searching, and see Subdirectory expansion). If you are using an up-to-date ls-R database (see 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 (see Filename database); font aliases (see Fontmap); and config file values (see 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.)

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.  See Debugging.

  * Perhaps you simply haven't installed all the necessary files; the basic fonts and input files are distributed separately from the programs. See 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 (see 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.  See 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 (see unixtex.ftp).

  * There is a bug in the library. See 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.  See 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 (see 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.  See Debugging.

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 (see 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 (see Config files (Dvips)).  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. See inimf invocation (Web2c).

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 Bugs (Using and Porting GNU CC).

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.

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.

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, see Online Metafont graphics (Web2c). 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.