texk 1

git-svn-id: svn://tug.org/texlive/trunk@1485 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 565 insertions, 0 deletions

diff --git a/Build/source/texk/kpathsea/BUGS b/Build/source/texk/kpathsea/BUGS
new file mode 100644
index 00000000000..42e61e01865
--- /dev/null
+++ b/Build/source/texk/kpathsea/BUGS
@@ -0,0 +1,565 @@
+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
+mchines 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.
+