summaryrefslogtreecommitdiff
path: root/Build/source/texk/kpathsea/BUGS
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/kpathsea/BUGS')
-rw-r--r--Build/source/texk/kpathsea/BUGS565
1 files changed, 0 insertions, 565 deletions
diff --git a/Build/source/texk/kpathsea/BUGS b/Build/source/texk/kpathsea/BUGS
deleted file mode 100644
index a3268c95ecb..00000000000
--- a/Build/source/texk/kpathsea/BUGS
+++ /dev/null
@@ -1,565 +0,0 @@
-Contents:
-
- 0.1 Reporting bugs
- 0.1.1 Bug checklist
- 0.1.2 Mailing lists
- 0.1.3 Debugging
- 0.1.4 Logging
- 0.1.5 Common problems
- 0.1.5.1 Unable to find files
- 0.1.5.2 Slow path searching
- 0.1.5.3 Unable to generate fonts
- 0.1.5.4 TeX or Metafont failing
- 0.1.5.5 Empty Makefiles
- 0.1.5.6 `XtStrings'
- 0.1.5.7 `dlopen'
- 0.1.5.8 `ShellWidgetClass'
- 0.1.5.9 Pointer combination warnings
-
-
-0.1 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, ...
-
-0.1.1 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.
-
-0.1.2 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).
-
-0.1.3 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'.)
-
-0.1.4 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.
-
-0.1.5 Common problems
----------------------
-
-Here are some common problems with configuration, compilation, linking,
-execution, ...
-
-0.1.5.1 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::.
-
-0.1.5.2 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::.
-
-0.1.5.3 Unable to generate fonts
-................................
-
-Metafont outputs fonts in bitmap format, tuned for a particular device
-at a particular resolution, in order to allow for the highest-possible
-quality of output. Some DVI-to-whatever programs, such as Dvips, try
-to generate these on the fly when they are needed, but this generation
-may fail in several cases.
-
- If `mktexpk' runs, but fails with this error:
- mktexpk: Can't guess mode for NNN dpi devices.
- mktexpk: Use a config file to specify the mode, or update me.
- you need to ensure the resolution and mode match; just specifying the
-resolution, as in `-D 360', is not enough.
-
- You can specify the mode name with the `-mode' option on the Dvips
-command line, or in a Dvips configuration file (*note Config files:
-(dvips)Config files.), such as `config.ps' in your document directory,
-`~/.dvipsrc' in your home directory, or in a system directory (again
-named `config.ps'). (Other drivers use other files, naturally.)
-
- For example, if you need 360dpi fonts, you could include this in a
-configuration file:
- D 360
- M lqmed
-
- If Metafont runs, but generates fonts at the wrong resolution or for
-the wrong device, most likely `mktexpk''s built-in guess for the mode
-is wrong, and you should override it as above.
-
- See `ftp://ftp.tug.org/tex/modes.mf' for a list of resolutions and
-mode names for most devices (additional submissions are welcome).
-
- 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.
-
- If `mf' is a command not found at all by `mktexpk', then you need to
-install Metafont (*note unixtex.ftp::).
-
-0.1.5.4 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
-machines when the native compiler is used, unless the `+u' compiler
-switch was specified. Using GCC will work on this platform as well.
-
-0.1.5.5 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.
-
-0.1.5.6 `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.
-
-0.1.5.7 `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.
-
-0.1.5.8 `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'.
-
-0.1.5.9 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.
-