--- /dev/null
+@include macros.texi
+@ifset rawfile
+@c documentencoding is used by makeinfo in our --no-headers output.
+@documentencoding ISO-8859-1
+@node Known problems,,(dir),(dir)
+@top Known problems
+
+@end ifset
+@c -----------------------
+@c @cindex @kbd{M-x preview-report-bug @key{RET}}
+@c @cindex @code{preview-report-bug}
+@c @cindex Report a bug
+A number of issues are known concerning the interoperation with various
+other software. Some of the known problems can be solved by moving to
+newer versions of the problematic software or by simple patches.
+
+@menu
+* Problems with Ghostscript::
+* Font problems with Dvips::
+* Emacs problems::
+* Too small bounding boxes::
+* x-symbol interoperation::
+* Middle-clicks paste instead of toggling::
+@end menu
+
+If you find something not mentioned here, please send a bug report using
+@kbd{M-x preview-report-bug @key{RET}}, which will fill in a lot of
+information interesting to us and send it to the
+@email{bug-auctex@@gnu.org} list. Please use the bug reporting commands
+if at all possible.
+
+@ifset rawfile
+@node Problems with Ghostscript
+@chapter Problems with Ghostscript
+@raisesections
+@end ifset
+@ifclear rawfile
+@node Problems with Ghostscript
+@section Problems with Ghostscript
+@end ifclear
+
+Most of the problems encountered come from interaction with Ghostscript.
+It is a good idea to have a fairly recent version of Ghostscript
+installed. One problem occurs if you have specified the wrong
+executable under Windows: the command line version of Ghostscript is
+called @file{GSWIN32C.EXE}, not @file{GSWIN32.EXE}.
+
+When Ghostscript fails, the necessary information and messages from
+Ghostscript go somewhere. If Ghostscript fails before starting to
+process images, you'll find the information at the end of the process
+buffer you can see with @kbd{C-c C-l}. If Ghostscript fails while
+processing a particular image, this image will be tagged with clickable
+buttons for the error description and for the corresponding source file.
+
+The default options configurable with
+
+@display
+@kbd{M-x customize-variable @key{RET} preview-gs-options @key{RET}}
+@end display
+@vindex preview-gs-options
+@noindent
+include the options @option{-dTextAlphaBits=4} and
+@option{-dGraphicsAlphaBits=4}. These options have been reported to
+make Ghostscript 5.50 fail, but should work under Ghostscript 6.51 and
+later. If you are experiencing problems, it might help to customize
+them away. Of course, this also takes away the joy of antialiasing, so
+upgrading Ghostscript might not be the worst idea after all.
+
+The device names have changed over time, so when using an old
+Ghostscript, you may have problems with the devices demanded by the
+customizable variable @code{preview-image-creators}.
+@vindex preview-image-creators
+In that case, make sure they fit your version of Ghostscript, at least
+the entry corresponding to the current value of
+@code{preview-image-type}.
+@vindex preview-image-type
+While not being best in file size and image quality, setting
+@code{preview-image-creators} to @code{jpeg} should probably be one of
+the best bets for the purpose of checking basic operation, since that
+device name has not changed in quite some time. But @acronym{JPEG} is
+not intended for text, but for photographic images. On a more
+permanent time scale, the best choice is to use @acronym{PNG} and
+complain to your suppliers if either Emacs or Ghostscript fail to
+properly accommodate this format.
+
+@node Font problems with Dvips
+@section Font problems with Dvips
+Some fonts have been reported to produce wrong characters with
+@previewlatex{}. @previewlatex{} calls Dvips by default with the option
+@option{-Pwww} in order to get scalable fonts for nice results. If you
+are using antialiasing, however, the results might be sufficiently nice
+with bitmapped fonts, anyway. You might try @option{-Ppdf} for another
+stab at scalable fonts, or other printer definitions. Use
+
+@display
+@kbd{M-x customize-variable @key{RET} preview-fast-dvips-command @key{RET}}
+@end display
+@noindent
+and
+@display
+@kbd{M-x customize-variable @key{RET} preview-dvips-command @key{RET}}
+@end display
+@noindent
+in order to customize this.
+
+One particular problem is that several printer setup files (typically in
+a file called @file{/usr/share/texmf/dvips/config/config.pdf} if you are
+using the @option{-Ppdf} switch) contain the @option{G} option for
+`character shifting'. This option will result in @samp{fi} being
+rendered as @samp{@pounds{}} (British Pounds sign) in several fonts,
+unless your version of Dvips has a long-standing bug in its
+implementation fixed (only very recent versions of Dvips have).
+
+@node Emacs problems
+@section Emacs problems
+
+@itemize @bullet
+@item GNU Emacs versions
+
+Don't use Emacsen older than 21.3 on X11-based systems. On most other
+systems, you'll need at least @w{Emacs 22.1} or one of the developer
+versions leading up to it. Details can be found in
+@ifset rawfile
+in the @file{INSTALL} file.
+@end ifset
+@ifclear rawfile
+@ref{Prerequisites,,,auctex,the @AUCTeX{} manual}.
+@end ifclear
+
+@item Emacsen on Windows operating systems
+
+For @w{Emacs 21}, no image support is available in Emacs under Windows.
+Without images, @previewlatex{} is useless. The current @acronym{CVS}
+version of Emacs available from
+@uref{http://savannah.gnu.org/projects/emacs} now supports images
+including the @acronym{PNG} format, so @w{Emacs 22} should work out of
+the box once it is released. Precompiled versions are available from
+@uref{http://crasseux.com/emacs} and @uref{http://nqmacs.sf.net}.
+
+For detailed installation instructions for Windows, see
+@ifset rawfile
+the file @file{INSTALL.windows}
+@end ifset
+@ifclear rawfile
+@ref{Installation under MS Windows,,,auctex,the @AUCTeX{} manual}.
+@end ifclear
+
+@item XEmacs
+
+There is are two larger problems known with older XEmacs releases. One
+leads to seriously mispositioned baselines and previews hanging far
+above other text on the same line. This should be fixed as of
+XEmacs-21.4.9.
+
+The other core bug causes a huge delay when XEmacs's idea of the state of
+processes (like ghostscript) is wrong, and can lead to nasty spurious
+error messages. It should be fixed in version 21.4.8.
+
+Previews will only remain from one session to the next if you have
+version 1.81 or above of the @file{edit-utils} package, first released
+in the 2002-03-12 sumo tarball.
+@end itemize
+
+@node Too small bounding boxes
+@section Too small bounding boxes
+The bounding box of a preview is determined by the @LaTeX{} package
+using the pure @TeX{} bounding boxes. If there is material extending
+outside of the @TeX{} box, that material will be missing from the
+preview image. This happens for the label-showing boxes from
+the @code{showkeys} package. This particular problem can be
+circumvented by using the @code{showlabels} option of the preview
+package.
+
+In general, you should try to fix the problem in the @TeX{} code, like
+avoiding drawing outside of the picture with PSTricks.
+
+One possible remedy is to set
+@code{preview-fast-conversion} to `Off'
+@ifset rawfile
+(see the manual).
+@end ifset
+@ifclear rawfile
+(@pxref{The Emacs interface}).
+@end ifclear
+The conversion will take more time, but will then use the bounding boxes
+from @acronym{EPS} files generated by Dvips.
+
+Dvips generally does not miss things, but it does not understand
+PostScript constructs like @code{\resizebox} or @code{\rotate} commands,
+so will generate rather wrong boxes for those. Dvips can be helped with
+the @code{psfixbb} package option to preview
+@ifset rawfile
+(see the manual),
+@end ifset
+@ifclear rawfile
+(@pxref{The LaTeX style file}),
+@end ifclear
+which will tag the corners of the included @TeX{} box. This will mostly
+be convenient for @emph{pure} PostScript stuff like that created by
+PSTricks, which Dvips would otherwise reserve no space for.
+
+@node x-symbol interoperation
+@section x-symbol interoperation
+
+Thanks to the work of Christoph Wedler, starting with version
+@samp{4.0h/beta} of x-symbol, the line parsing of @AUCTeX{} and
+@previewlatex{} is fully supported. Earlier versions exhibit problems.
+However, versions before 4.2.2 will cause a drastic slowdown of
+@previewlatex{}'s parsing pass, so we don't recommend to use versions
+earlier than that.
+
+If you wonder what x-symbol is, it is a package that transforms various
+tokens and subscripts to a more readable form while editing and offers a
+few input methods handy especially for dealing with math. Take a look at
+@uref{http://x-symbol.sourceforge.net}.
+
+x-symbol versions up to 4.5.1-beta at least require an 8bit-clean @TeX{}
+implementation (meaning that its terminal output should not use
+@samp{^^}-started escape sequences) for cooperation with
+@previewlatex{}. Later versions may get along without it, like
+@previewlatex{} does now.
+
+If you experience problems with @file{circ.tex} in connection with both
+x-symbol and Latin-1 characters, you may need to change your language
+environment or, as a last resort, customize the variable
+@code{LaTeX-command-style} by replacing the command @code{latex} with
+@code{latex -translate-file=cp8bit}.
+
+@node Middle-clicks paste instead of toggling
+@section Middle-clicks paste instead of toggling
+
+This is probably the fault of your favorite package. @file{flyspell.el}
+and @file{mouse-drag.el} are known to be affected in versions before
+@w{Emacs 21.3}. Upgrade to the most recent version. What version of
+XEmacs might contain the fixes is unknown.
+
+@file{isearch.el} also shows this effect while searches are in progress,
+but the code is such a complicated mess that no patch is in sight.
+Better just end the search with @kbd{@key{RET}} before toggling and
+resume with @kbd{C-s C-s} or similar afterwards. Since previews over
+the current match will auto-open, anyway, this should not be much of a
+problem in practice.