summaryrefslogtreecommitdiff
path: root/Build/source/texk/kpathsea/doc/bugs.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/kpathsea/doc/bugs.texi')
-rw-r--r--Build/source/texk/kpathsea/doc/bugs.texi901
1 files changed, 901 insertions, 0 deletions
diff --git a/Build/source/texk/kpathsea/doc/bugs.texi b/Build/source/texk/kpathsea/doc/bugs.texi
new file mode 100644
index 00000000000..4ec2d560a57
--- /dev/null
+++ b/Build/source/texk/kpathsea/doc/bugs.texi
@@ -0,0 +1,901 @@
+@ifclear version
+@defcodeindex fl
+@defcodeindex op
+@end ifclear
+
+@node Reporting bugs
+@section Reporting bugs
+
+@cindex reporting bugs
+@cindex bugs, reporting
+
+@ifset version
+(A copy of this chapter is in the file @file{kpathsea/BUGS}.)
+@end ifset
+
+@flindex tex-k@@mail.tug.org @r{(bug address)}
+@cindex bug address
+If you have problems or suggestions, please report them to
+@email{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, @dots{}
+
+@menu
+* Bug checklist:: What to include in a good bug report.
+* Mailing lists:: Joining the bugs or announcements mailing lists.
+* Debugging:: Analyzing runtime problems.
+* Logging:: Recording searches.
+* Common problems:: When things go wrong.
+@end menu
+
+
+@node Bug checklist
+@subsection Bug checklist
+
+@cindex checklist for bug reports
+@cindex bug checklist
+
+Before reporting a bug, please check below to be sure it isn't already
+known (@pxref{Common problems}).
+
+Bug reports should be sent via electronic mail to
+@email{tex-k@@mail.tug.org}.
+
+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:
+
+@itemize @bullet
+@item
+@cindex version numbers, determining
+The version number(s) of the program(s) involved, and of Kpathsea
+itself. You can get the former by giving a sole option @samp{--version}
+to the program, and the latter by running @samp{kpsewhich --version}.
+The @file{NEWS} and @file{ChangeLog} files also contain the version
+number.
+
+@item
+@pindex uname
+The hardware, operating system (including version number), compiler, and
+@code{make} program you are using (the output of @code{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).
+
+@item
+@flindex config.log
+Any options you gave to @code{configure}. This is recorded in the
+@file{config.status} files.
+
+@cindex configuration bugs
+@flindex config.status
+If you are reporting a bug in @samp{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 @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 @samp{configure} bugs do not involve the
+compiler; in that case, the only recourse is to inspect the
+@code{configure} shell script itself, or the Autoconf macros that
+generated @code{configure}.
+
+@item
+The log of all debugging output, if the bug is in path searching. You
+can get this by setting the environment variable @code{KPATHSEA_DEBUG}
+to @samp{-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.
+
+@item
+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.
+
+@item
+@cindex context diff
+@cindex sending patches
+@flindex ChangeLog @r{entry}
+If you are sending a patch (do so if you can!), please do so in the form
+of a context diff (@samp{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 @file{ChangeLog} entry.
+
+@item
+@cindex stack trace
+@cindex debugger
+@cindex crashes, reporting
+@cindex core dumps, reporting
+@cindex null pointers, dereferencing
+@pindex gdb@r{, recommended}
+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 @url{ftp://prep.ai.mit.edu/pub/gnu}). If
+the cause is apparent (a @code{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 (@pxref{TeX or Metafont failing,, @TeX{} or Metafont
+failing}).
+
+@item
+Any additional information that will be helpful in reproducing,
+diagnosing, or fixing the bug.
+@end itemize
+
+
+@node Mailing lists
+@subsection Mailing lists
+
+@cindex mailing lists
+@cindex bug mailing list
+@cindex announcement mailing list
+
+Web2c and Kpathsea in general are discussed on the mailing list
+@email{tex-k@@mail.tug.org}.
+@flindex tex-k-request@@mail.tug.org
+To join, email @email{tex-k-request@@mail.tug.org} with a line
+consisting of
+
+@example
+subscribe @var{you}@@@var{your.preferred.email.address}
+@end example
+
+@noindent 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 @samp{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 @url{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.
+
+@flindex tex-archive@@math.utah.edu
+@cindex announcement mailing list
+If you only want announcements of new releases, not bug reports and
+discussion, join @email{tex-archive@@math.utah.edu} (via mail to
+@email{tex-archive-request@@math.utah.edu}).
+
+@cindex @TeX{} help mailing list
+@cindex La@TeX{} help mailing list
+@cindex Usenet @TeX{} newsgroup
+@cindex newsgroup for @TeX{}
+@cindex help, mailing list for general @TeX{}
+@flindex info-tex@@shsu.edu
+@flindex comp.text.tex
+If you are looking for general @TeX{} help, such as how to use La@TeX{},
+please use the mailing list @email{info-tex@@shsu.edu} mailing list,
+which is gatewayed to the @samp{comp.text.tex} Usenet newsgroup (or post
+to the newsgroup; the gateway is bidirectional).
+
+
+@node Debugging
+@subsection Debugging
+
+@cindex debugging
+@cindex runtime debugging
+@cindex options for debugging
+
+@vindex kpathsea_debug
+@flindex debug.h
+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., @samp{-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 @samp{-d} (or whatever) option
+first, for maximal output. Dvipsk and Xdvik have additional
+program-specific debugging options as well.
+
+@vindex KPATHSEA_DEBUG
+@vindex kpathsea_debug
+You can also set the environment variable @code{KPATHSEA_DEBUG}; in this
+case, you should use the numbers below. If you run the program under a
+debugger and set the variable @code{kpathsea_debug}, also use the numbers
+below.
+
+@kindex -1 @r{debugging value}
+In any case, by far the simplest value to use is @samp{-1}, which will
+turn on all debugging output. This is usually better than guessing
+which particular values will yield the output you need.
+
+@cindex debugging output
+@cindex standard error and debugging output
+Debugging output always goes to standard error, so you can redirect it
+easily. For example, in Bourne-compatible shells:
+@example
+dvips -d -1 @dots{} 2>/tmp/debug
+@end example
+
+@cindex Kpsewhich, and debugging
+It is sometimes helpful to run the standalone Kpsewhich utility
+(@pxref{Invoking kpsewhich}), instead of the original program.
+
+@cindex numeric debugging values
+In any case, you can @emph{not} use the @emph{names} below; you must
+always use somebody's numbers. (Sorry.) To set more than one
+option, just sum the corresponding numbers.
+
+@vtable @code
+@item KPSE_DEBUG_STAT @r{(1)}
+Report @samp{stat}(2) calls. This is useful for verifying that your
+directory structure is not forcing Kpathsea to do many additional file
+tests (@pxref{Slow path searching}, and @pxref{Subdirectory
+expansion}). If you are using an up-to-date @file{ls-R} database
+(@pxref{Filename database}), this should produce no output unless a
+nonexistent file that must exist is searched for.
+
+@item KPSE_DEBUG_HASH @r{(2)}
+Report lookups in all hash tables: @file{ls-R} and @file{aliases}
+(@pxref{Filename database}); font aliases (@pxref{Fontmap}); and config
+file values (@pxref{Config files}). Useful when expected values are not
+being found, e.g.., file searches are looking at the disk instead of
+using @file{ls-R}.
+
+@item KPSE_DEBUG_FOPEN @r{(4)}
+@findex fopen@r{, redefined}
+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 @samp{fopen} (@samp{fclose}) to be @samp{kpse_fopen_trace}
+(@samp{kpse_fclose_trace}).
+
+@item KPSE_DEBUG_PATHS @r{(8)}
+@tindex kpse_format_info_type
+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 @file{texmf.cnf}, @file{config.ps},
+an environment variable, the compile-time default, etc. This is the
+contents of the @code{kpse_format_info_type} structure defined in
+@file{tex-file.h}.
+
+@item KPSE_DEBUG_EXPAND @r{(16)}
+Report the directory list corresponding to each path element Kpathsea
+searches. This is only relevant when Kpathsea searches the disk, since
+@file{ls-R} searches don't look through directory lists in this way.
+
+@item KPSE_DEBUG_SEARCH @r{(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
+@file{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.,
+@file{texmf.cnf} and @file{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.
+
+@item KPSE_DEBUG_VARS @r{(64)}
+Report the value of each variable Kpathsea looks up. This is useful for
+verifying that variables do indeed obtain their correct values.
+
+@item GSFTOPK_DEBUG @r{(128)}
+Activates debugging printout specific to @code{gsftopk} program.
+
+@item MAKETEX_DEBUG @r{(512)}
+If you use the optional @code{mktex} programs instead of the
+traditional shell scripts, this will report the name of the site file
+(@file{mktex.cnf} by default) which is read, directories created by
+@code{mktexdir}, the full path of the @file{ls-R} database built by
+@code{mktexlsr}, font map searches, @code{MT_FEATURES} in effect,
+parameters from @code{mktexnam}, filenames added by
+@code{mktexupd}, and some subsidiary commands run by the programs.
+
+@item MAKETEX_FINE_DEBUG @r{(1024)}
+When the optional @code{mktex} programs are used, this will print
+additional debugging info from functions internal to these programs.
+@end vtable
+
+@cindex @samp{kdebug:}
+@vindex hash_summary_only @r{variable for debugging}
+@cindex hash table buckets, printing
+Debugging output from Kpathsea is always written to standard error, and
+begins with the string @samp{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 @code{hash_summary_only}
+variable in @file{kpathsea/db.c}.)
+
+
+@node Logging
+@subsection Logging
+
+@cindex log file
+
+@cindex logging successful searches
+@cindex recording successful searches
+@cindex usage patterns, finding
+@cindex disk usage, reducing
+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.
+
+@vindex TEXMFLOG
+To do this, define the environment or config file variable
+@code{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.
+
+@cindex epoch, seconds since
+@findex time @r{system call}
+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 @code{time} system
+call). The second word is the filename.
+
+For example, after @code{setenv TEXMFLOG /tmp/log}, running Dvips on
+@file{story.dvi} appends the following lines:
+
+@example
+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
+@end example
+
+@cindex privacy, semblance of
+@noindent Only filenames that are absolute are recorded, to preserve
+some semblance of privacy.
+
+In addition to this Kpathsea-specific logging, @command{pdftex}
+provides an option @option{-recorder} to write the names of all files
+accessed during a run to the file @file{@var{basefile}.fls}.
+
+Finally, most systems provide a general tool to output each system
+call, thus including opening and closing files. It might be named
+@command{strace}, @command{truss}, @command{struss}, or something
+else.
+
+
+@node Common problems
+@subsection Common problems
+
+@cindex common problems
+@cindex problems, common
+@cindex FAQ, Kpathsea
+
+Here are some common problems with configuration, compilation, linking,
+execution, @dots{}
+
+@menu
+* Unable to find files:: If your program can't find fonts (or whatever).
+* Slow path searching:: If it takes forever to find anything.
+* Unable to generate fonts:: If mktexpk fails.
+* TeX or Metafont failing:: Likely compiler bugs.
+
+* Empty Makefiles:: When configure produces empty makefiles.
+* XtStrings:: When _XtStrings is undefined.
+* dlopen:: When dlopen is undefined.
+* ShellWidgetClass:: For dynamic linking troubles under OpenWindows.
+* Pointer combination warnings:: For old compilers that don't grok char *.
+@end menu
+
+@node Unable to find files
+@subsubsection Unable to find files
+
+@cindex unable to find files
+@cindex files, unable to find
+
+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. @xref{Debugging}.
+
+@itemize @bullet
+@item
+Perhaps you simply haven't installed all the necessary files; the basic
+fonts and input files are distributed separately from the programs.
+@xref{unixtex.ftp}.
+
+@item
+@flindex /etc/profile
+@cindex environment variables, old
+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 @file{texmf.cnf} (@pxref{Supported file
+formats}). System @file{/etc/profile} or other files such may be the
+culprit.
+
+@item
+@cindex symbolic links not found
+@cindex leaf directories wrongly guessed
+Your files reside in a directory that is only pointed to via a symbolic
+link, in a leaf directory and is not listed in @file{ls-R}.
+
+Unfortunately, Kpathsea's subdirectory searching has an irremediable
+deficiency: If a directory @var{d} being searched for subdirectories
+contains plain files and symbolic links to other directories, but no
+true subdirectories, @var{d} will be considered a leaf directory, i.e.,
+the symbolic links will not be followed. @xref{Subdirectory expansion}.
+
+You can work around this problem by creating an empty dummy subdirectory
+in @var{d}. Then @var{d} will no longer be a leaf, and the symlinks will
+be followed.
+
+The directory immediately followed by the @samp{//} 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.
+
+@item
+If the fonts (or whatever) don't already exist, @code{mktexpk} (or
+@code{mktexmf} or @code{mktextfm}) will try to create them. If
+these rather complicated shell scripts fail, you'll eventually get an
+error message saying something like @samp{Can't find font
+@var{fontname}}. The best solution is to fix (or at least report) the
+bug in @code{mktexpk}; the workaround is to generate the necessary
+fonts by hand with Metafont, or to grab them from a CTAN site
+(@pxref{unixtex.ftp}).
+
+@item
+There is a bug in the library. @xref{Reporting bugs}.
+@end itemize
+
+
+@node Slow path searching
+@subsubsection Slow path searching
+
+@cindex excessive startup time
+@cindex slow startup time
+@cindex startup time, excessive
+
+If your program takes an excessively long time to find fonts or other
+input files, but does eventually succeed, here are some possible culprits:
+
+@itemize @bullet
+@item
+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 @file{ls-R} file that lists all the files in your main @TeX{}
+hierarchy. @xref{Filename database}. Kpathsea always uses @file{ls-R}
+if it's present; there's no need to recompile or reconfigure any of the
+programs.
+
+@item
+Your recursively-searched directories (e.g.,
+@file{/usr/local/share/texmf/fonts//}), contain a mixture of files and
+directories. This prevents Kpathsea from using a useful optimization
+(@pxref{Subdirectory expansion}).
+
+It is best to have only directories (and perhaps a @file{README}) in the
+upper levels of the directory structure, and it's very important to have
+@emph{only} files, and no subdirectories, in the leaf directories where
+the dozens of TFM, PK, or whatever files reside.
+@end itemize
+
+In any case, you may find the debugging options helpful in determining
+precisely when the disk or network is being pounded. @xref{Debugging}.
+
+
+@node Unable to generate fonts
+@subsubsection Unable to generate fonts
+
+@cindex unable to generate fonts
+@cindex font generation failures
+
+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.
+
+@cindex @code{mktexpk} can't guess mode
+If @code{mktexpk} runs, but fails with this error:
+@example
+mktexpk: Can't guess mode for @var{nnn} dpi devices.
+mktexpk: Use a config file to specify the mode, or update me.
+@end example
+you need to ensure the resolution and mode match; just
+specifying the resolution, as in @code{-D 360}, is not enough.
+
+You can specify the mode name with the @code{-mode} option on the
+Dvips command line, or in a Dvips configuration file (@pxref{Config
+files,,, dvips, Dvips}), such as @file{config.ps} in your document
+directory, @file{~/.dvipsrc} in your home directory, or in a system
+directory (again named @file{config.ps}). (Other drivers use other
+files, naturally.)
+
+For example, if you need 360@dmn{dpi} fonts, you could include this in
+a configuration file:
+@example
+D 360
+M lqmed
+@end example
+
+@cindex Metafont using the wrong device
+@cindex device, wrong
+If Metafont runs, but generates fonts at the wrong resolution or for
+the wrong device, most likely @code{mktexpk}'s built-in guess for the
+mode is wrong, and you should override it as above.
+
+See @url{ftp://ftp.tug.org/tex/modes.mf} for a list of resolutions and
+mode names for most devices (additional submissions are welcome).
+
+@flindex .2602gf
+@flindex 2602gf
+@cindex Metafont making too-large fonts
+@cindex proof mode
+@cindex online Metafont display, spurious
+If Metafont runs but generates fonts at a resolution of 2602@dmn{dpi}
+(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
+@code{proof} mode, instead of an actual device mode.) To make a proper
+@file{plain.base}, assuming the local mode definitions are contained in
+a file @file{modes.mf}, run the following command (assuming Unix):
+
+@example
+inimf "plain; input modes; dump"
+@end example
+
+@noindent
+@flindex plain.base
+Then copy the @file{plain.base} file from the current directory to where
+the base files are stored on your system
+(@file{/usr/local/share/texmf/web2c} by default), and make a link
+(either hard or soft) from @file{plain.base} to @file{mf.base} in that
+directory.
+@xref{inimf invocation,,, web2c, Web2c}.
+
+@cindex Metafont installation
+If @code{mf} is a command not found at all by @code{mktexpk}, then you
+need to install Metafont (@pxref{unixtex.ftp}).
+
+
+@node TeX or Metafont failing
+@subsubsection @TeX{} or Metafont failing
+
+@cindex @TeX{} failures
+@cindex Metafont failures
+@cindex compiler bugs
+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.
+
+@cindex optimization caveat
+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.
+
+@cindex GNU C compiler bugs
+@cindex system C compiler bugs
+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 @ref{Bugs,,, gcc,
+Using and Porting GNU CC}.
+
+@cindex compiler bugs, finding
+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.
+
+@cindex ANSI C
+@cindex HP-UX, compiling on
+@cindex compiling on HP-UX
+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 @samp{+u} compiler
+switch was specified. Using GCC will work on this platform as well.
+
+@node Empty Makefiles
+@subsubsection Empty Makefiles
+
+@cindex Makefiles, empty
+@pindex sed @r{error from @code{configure}}
+@pindex configure @r{error from @code{sed}}
+@cindex NetBSD @code{configure} error
+@cindex FreeBSD @code{configure} error
+@cindex Mach10 @code{configure} error
+@cindex AIX 4.1 @code{configure} error
+@cindex NeXT @code{sed} error
+
+On some systems (NetBSD, FreeBSD, AIX 4.1, and Mach10), @code{configure}
+may fail to properly create the Makefiles. Instead, you get an error
+which looks something like this:
+
+@example
+prompt$ ./configure
+@dots{}
+creating Makefile
+sed: 1: "\\@@^ac_include make/pat ...": \ can not be used as a string delimiter
+@end example
+
+So far as I know, the bug here is in @code{/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 @code{ac_include} in the @code{configure} script
+to get to the problematic code.)
+
+It should work to run @code{bash configure}, instead of using
+@code{/bin/sh}. You can get Bash from
+@url{ftp://prep.ai.mit.edu/pub/gnu} and mirrors.
+
+Another possible cause (reported for NeXT) is a bug in the @code{sed}
+command. In that case the error may look like this:
+
+@example
+Unrecognized command: \@@^ac_include make/paths.make@@r make/paths.make
+@end example
+
+In this case, installing GNU @code{sed} should solve the problem. You
+can get GNU @code{sed} from the same places as Bash.
+
+@ignore
+@node wchar_t
+@subsubsection @code{wchar_t}
+
+@vindex FOIL_X_WCHAR_T
+@tindex wchar_t
+
+The upshot of all the following is that if you get error messages
+regarding @code{wchar_t}, try defining @code{NO_FOIL_X_WCHAR_T} (for
+Web2c) or @code{FOIL_X_WCHAR_T} (for everything else), as in:
+
+@example
+make XCFLAGS=-DNO_FOIL_X_WCHAR_T @var{other-make-options}
+@end example
+
+@flindex Xlib.h
+@flindex stddef.h
+@code{wchar_t} has caused infinite trouble. None of my code ever uses
+@code{wchar_t}; all I want to do is include X header files and various
+system header files, possibly compiling with GCC. This seems an
+impossible task! The basic problem is that the X11 header
+@file{<Xlib.h>} and GCC's @file{<stddef.h>} have conflicting definitions
+for @code{wchar_t}.
+
+The particulars: @file{<X11/Xlib.h>} from MIT X11R5 defines
+@code{wchar_t} if @code{X_WCHAR} is defined, which is defined if
+@code{X_NOT_STDC_ENV} is defined, and we define @emph{that} if
+@code{STDC_HEADERS} is not defined (@samp{configure} decides if
+@code{STDC_HEADERS} gets defined). But when compiling with GCC on SunOS
+4.1.x, @code{STDC_HEADERS} is not defined (@file{string.h} doesn't
+declare the @samp{mem}* functions), so we do get X's
+@code{wchar_t}---and we also get GCC's @code{wchar_t} from its
+@file{<stddef.h>}. Conflict.
+
+On the other hand, SunOS 4.1.1 with some other X configurations actually
+needs GCC to define @code{wchar_t}, and fails otherwise.
+
+My current theory is to define @code{wchar_t} to a nonsense symbol
+before the X include files are read; that way its definition (if any)
+will be ignored by other system include files. Going along with that,
+define @code{X_WCHAR} to tell X not to use @file{<stddef.h>}, that we've
+already included, but instead to make its own definition.
+
+But this is not the end of the story. The X11 include files distributed
+with DG/UX 5.4.2 for the Aviion have been modified to include
+@file{<_int_wchar_t.h>} if @code{X_WCHAR}, so our @code{#define} will
+not have any typedef to change---but the uses of @code{wchar_t} in the X
+include files will be changed to reference this undefined symbol. So
+there's nothing to foil in this case. I don't know how to detect this
+automatically, so it's up to you to define @code{NO_FOIL_X_WCHAR_T}
+yourself.
+@end ignore
+
+@node XtStrings
+@subsubsection @code{XtStrings}
+
+@findex XtStrings
+You may find that linking X programs results in an error from the linker
+that @samp{XtStrings} is undefined, something like this:
+
+@example
+gcc -o virmf @dots{}
+@dots{}/x11.c:130: undefined reference to `XtStrings'
+@end example
+
+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 @samp{configure} was unable to guess the proper
+directories from your installation. You can use the @code{configure}
+options @samp{--x-includes=@var{path}} and
+@samp{--x-libraries=@var{path}} to explicitly specify them.
+
+
+@node dlopen
+@subsubsection @code{dlopen}
+
+@cindex static linking and @code{dlsym}
+@flindex dlopen
+@flindex dlsym
+@flindex dlclose
+@flindex wcstombs
+@flindex libdl.a
+(This section adapted from the file @file{dlsym.c} in the X distribution.)
+
+The @code{Xlib} library uses the standard C function @code{wcstombs}.
+Under SunOS 4.1, @code{wcstombs} uses the @samp{dlsym} interface defined
+in @file{libdl.so}. Unfortunately, the SunOS 4.1 distribution does not
+include a static @samp{libdl.a} library.
+
+As a result, if you try to link an X program statically under SunOS, you
+may get undefined references to @code{dlopen}, @code{dlsym}, and
+@code{dlclose}. One workaround is to include these definitions
+when you link:
+
+@example
+void *dlopen() @{ return 0; @}
+void *dlsym() @{ return 0; @}
+int dlclose() @{ return -1; @}
+@end example
+
+@flindex dlsym.c
+@noindent These are contained in the @file{dlsym.c} file in the MIT X
+distribution.
+
+
+@node ShellWidgetClass
+@subsubsection @code{ShellWidgetClass}
+
+@cindex dynamic linking problems with OpenWin libraries
+@cindex OpenWin libraries, dynamic linking problems
+@findex get_wmShellWidgetClass
+@findex get_applicationShellWidgetClass
+
+@flindex comp.sys.sun.admin @r{FAQ}
+@cindex FAQ, @t{comp.sys.sun.admin}
+(This section adapted from the @t{comp.sys.sun.admin} FAQ.)
+
+If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x, you
+may get undefined symbols @code{_get_wmShellWidgetClass} and
+@code{_get_applicationShellWidgetClass} when linking. This problem does
+not arise using the standard MIT X libraries under SunOS.
+
+@findex Xmu @r{library problems}
+The cause is bugs in the @code{Xmu} shared library as shipped from Sun.
+There are several fixes:
+
+@itemize @bullet
+
+@item Install the free MIT distribution from @samp{ftp.x.org} and mirrors.
+
+@item Get the OpenWindows patches listed below.
+
+@item Statically link the @code{Xmu} library into the executable.
+
+@item Avoid using @code{Xmu} at all. If you are compiling
+Metafont, see @ref{Online Metafont graphics,,, web2c, Web2c}. If you are
+compiling Xdvi, see the @code{-DNOTOOL} option in @file{xdvik/INSTALL}.
+
+@item Ignore the errors. The binary runs fine regardless.
+
+@end itemize
+
+@cindex Sun OpenWin patches
+@cindex patches, Sun OpenWin
+Here is the information for getting the two patches:
+
+@display
+Patch ID: 100512-02
+Bug ID's: 1086793, 1086912, 1074766
+Description: 4.1.x OpenWindows 3.0 @code{libXt} jumbo patch
+
+Patch ID: 100573-03
+Bug ID: 1087332
+Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared @code{libXmu}.
+@end display
+
+@cindex static linking
+The way to statically link with @code{libXmu} depends on whether you are
+using a Sun compiler (e.g., @code{cc}) or @code{gcc}. If the latter,
+alter the @code{x_libs} Make variable to include
+
+@opindex -static
+@opindex -dynamic
+@example
+-static -lXmu -dynamic
+@end example
+
+@opindex -Bstatic
+@opindex -Bdynamic
+If you are using the Sun compiler, use @samp{-Bstatic} and @samp{-Bdynamic}.
+
+
+@node Pointer combination warnings
+@subsubsection Pointer combination warnings
+
+@cindex warnings, pointer combinations
+@cindex pointer combination warnings
+@cindex illegal pointer combination warnings
+@pindex cc @r{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.
+
+@c This isn't worth including any more, OSF 1.x is too old.
+@c The other XtInherit problem (R4 Xlib on Suns) should never come up,
+@c but the answer from the X faq is included anyway.
+@c
+@c @node XtInherit
+@c @subsubsection @code{XtInherit}
+@c
+@c @findex XtInherit @r{bug on OSF/1}
+@c @cindex OSF/1 loader bug and @code{XtInherit}
+@c @cindex Alpha OSF/1 loader bug and @code{XtInherit}
+@c
+@c On DEC OSF/1 1.x systems, the loader has a bug that manifests itself in
+@c the following error (all on one line, but for the sake of the paper
+@c width it's broken here):
+@c
+@c @example
+@c xdvik/xdvi: /sbin/loader: Fatal Error: search_for_undefineds:
+@c symbol _XtInherit should not have any relocation entry
+@c @end example
+@c
+@c @noindent According to Michael Rickabaugh @code{<mjr@@quarry.enet.dec.com>}:
+@c
+@c @quotation
+@c This is a bug fixed in DEC OSF/1 2.0.
+@c
+@c If you know how, installing @file{/sbin/loader} from a 2.0 system onto a
+@c 1.3 system will work. Make sure that @file{/usr} is @emph{not} mounted
+@c when you do this. (If you forget about umounting @code{/usr}, it is
+@c possible most of your filesystems will become corrupted.)
+@c
+@c Otherwise, I suggest getting a later CD and running
+@c @file{/usr/sbin/installupdate}.
+@c @end quotation
+@c
+@c Alternatively, you may be able to use the freely available X11 libraries
+@c that come with the MIT distribution (on @file{ftp.x.org}, for example).
+@c
+@c Linking statically, perhaps only with some of the X libraries, may also
+@c work.
+@c
+@c The Sun XtInherit weirdness, from the comp.windows.x FAQ:
+@c Subject: 126)! What are these problems with "*_XtInherit* not found" on the Sun?
+@c When I link a X program that I wrote on a SunOS 4.0.3 or 4.1 machine I get the
+@c error "ld.so: symbol not found *_XtInherit*".
+@c
+@c What you are seeing is a side-effect of a kludge in the R4 libXt.a to
+@c get Sun shared libraries working. Apparently, you can't share a function that
+@c is both called and compared, as *_XtInherit* is. This was handled by putting
+@c *_XtInherit* in the same file as a function that is always used, thereby
+@c guaranteeing that it would be loaded -- that is, in Initialize.c, where
+@c XtToolkitInitialize() and XtInitialize() reside. These routines would normally
+@c be called.
+@c
+@c You are probably seeing this error because your program is not a normal
+@c Xt-based program and does not call XtToolkitInitialize() anywhere.
+@c 1) it may be a program that uses Xt functions but never opens a
+@c connection to the X server. [OSF/Motif's 1.1.0 UIL had this problem; it called
+@c XtMalloc() and other Xt functions.] The solution is to add the call to your
+@c program; the function does not have to be executed, just linked in.
+@c 2) alternatively, your program doesn't need any Xt functions and is
+@c correct in not calling XtToolkitInitialize() -- it may be an Xlib or XView
+@c program. In this case, you can remove -lXt from your link command.
+@c
+@c It should not be necessary to link the shared libraries statically,
+@c although this will certainly solve the problem.
+
+@c * Empty Makefiles:: If configure gives you sed errors.
+@c * wchar_t:: For wchar_t difficulties.