@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.
