diff options
Diffstat (limited to 'Build/source/texk/kpathsea/BUGS')
| -rw-r--r-- | Build/source/texk/kpathsea/BUGS | 565 |
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. - |