Known problems
**************

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.

   If you find something not mentioned here, please send a bug report
using `M-x preview-report-bug <RET>', which will fill in a lot of
information interesting to us.  Some bugs are being fixed as you read
this, there is a mailing list for developers, look at
`http://lists.sourceforge.net/lists/listinfo/preview-latex-devel'.  For
more information on the mailing list, send a message with just the word
"help" as subject or body to
<preview-latex-devel-request@lists.sourceforge.net>. Questions,
suggestions for new features, and pleas for help should go to
<preview-latex-devel@lists.sourceforge.net> (the preview-latex devel
team).

Problems with GhostScript
=========================

   Most of the problems encountered come from interaction with
GhostScript.  It is a good idea to have a fairly recent version of
GhostScript installed.

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

   *Important note:* Various versions of GhostScript have a security
bug which could seriously affect preview-latex.  Current versions of
preview-latex should work around this bug.  The symptom would be that
one out of two previews will fail, and previews get generated quite
slowly since preview-latex starts a new GhostScript process after each
failure.  Please report any reoccurence of the problem.

   The default options configurable with

     M-x customize-variable <RET> preview-gs-options <RET>

include the options `-dTextAlphaBits=4' and `-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 `preview-image-creators'.  In that case, make
sure they fit your version of GhostScript, at least the entry
corresponding to the current value of `preview-image-type'.  While not
being best in file size and image quality, setting
`preview-image-creators' to `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 JPEG is not intended for
text, but for photographic images.  On a more permanent time scale, the
best choice is to use PNG and complain to your suppliers if either
Emacs or GhostScript fail to properly accommodate this format.

Font problems with Dvips
========================

   Some fonts have been reported to produce wrong characters with
preview-latex.  preview-latex calls Dvips by default with the 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 `-Ppdf' for another stab
at scalable fonts, or other printer definitions.  Use

     M-x customize-variable <RET> preview-fast-dvips-command <RET>

and
     M-x customize-variable <RET> preview-dvips-command <RET>

in order to customize this.

   One particular problem is that several printer setup files
(typically in a file called `/usr/share/texmf/dvips/config/config.pdf'
if you are using the `-Ppdf' switch) contain the `G' option for
`character shifting'.  This option will result in `fi' being rendered
as `#' (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).

Emacs problems
==============

   * GNU Emacs versions prior to 21.1

     Don't use them.  20.x will not work, 21.0.x were prereleases,
     anyway.

   * Emacsen on Windows operating systems

     As of GNU Emacs 21.2, no image support is available in Emacs under
     Windows.  Without images, preview-latex is useless.  The current
     CVS version of Emacs available from
     `http://savannah.gnu.org/projects/emacs' now supports images
     including the PNG format, so Emacs 21.4 should work out of the box
     once it is released.  Another option for Windows users might be to
     try XEmacs.  preview-latex has successfully been installed with
     recent CVS versions of GNU Emacs, and both Cygwin XEmacs and the
     native Windows XEmacs.

     See the file `INSTALL.windows' for detailed installation
     instructions for this platform.

   * 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 `edit-utils' package, first released
     in the 2002-03-12 sumo tarball.

AUCTeX prior to 11.0
====================

   AUCTeX versions up to and including 10.0g have a bug in the
calculation of the offsets for the start of a region.  This affects
`C-c C-r' commands where the start of the region does not lie on the
start of a line.  It also affects regeneration of single previews.  To
correct this, apply the patch in `patches/auctex-10.patch'.  It might
be more prudent to install a more recent version of AUCTeX, however.

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. For example this happens for the label-showing boxes from the
`showkeys' package (which has its own variant in preview-latex). Should
this happen to you, try setting `preview-fast-conversion' to `Off' (see
the manual).  The conversion will take slightly more time, but instead
use the bounding boxes from the EPS files generated by Dvips.

   Dvips generally does not miss things, but it does not understand
PostScript constructs like `\resizebox' or `\rotate' commands, so will
generate rather wrong boxes for those.  Dvips can be helped with the
`psfixbb' package option to preview (see the manual), which will tag
the corners of the included TeX box.  This will mostly be convenient
for _pure_ PostScript stuff like that created by PStricks, which Dvips
would otherwise reserve no space for.

LaTeX international characters
==============================

   To determine the position of a preview, preview-latex correlates
error messages from TeX with the input text.  The delivered example
file `circ.tex' contains `ISO-8859-1' input characters (also called
`Latin-1').  If your language environment is not properly set up, or
your TeX version is rather old, TeX will, for example, display `'
(German u-Umlaut) as `^^fc'.  In that case the correlation will fail,
with the result that the preview images get misplaced.  Personally, I
have set the environment variable `LANG' to the string
`en_US.ISO8859-1'.  Your system may have different ways of achieving
something similar.  If you have a graphical login screen, chances are
that it offers a `Language' setting.  It may help to choose `US
English' or similar instead of the plain `English' setting.  This
problem has also been reported as being caused by teTeX compiled
against `libc5' libraries.

   `configure' currently tries checking for an 8-bit-clean
configuration of LaTeX and refuses to continue until you have fixed it.
If nothing else works and you would not need to have an 8-bit clean
installation, pass the option `--disable-8bit-test' to configure.  This
will usually result in `circ.tex' and other files with 8-bit characters
not being properly previewed.

   As a very last resort, when all of the regular attempts of getting
your system recognized as being able to deal with 8-bit characters by
the `latex' executable fail, you might try to use `M-x
customize-variable' on the variable `LaTeX-command-style' and replace
the command `latex' with `latex -translate-file=cp8bit'.

x-symbol interoperation
=======================

   Thanks to the work of Christoph Wedler, starting with version
`4.0h/beta' of x-symbol, the line parsing of AUCTeX and preview-latex
is fully supported.  Earlier versions exhibit problems.  However,
versions before 4.2.2 will cause a drastic slowdown of preview-latex'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 `http://x-symbol.sourceforge.net'.

Middle-clicks paste instead of toggling
=======================================

   This is probably the fault of your favorite package.  In Emacs-21.1,
the following culprits are known; Emacs-21.2 inherits those bugs, as of
21.3, they will be fixed.  The patches have been thoroughly tested and
applying them is hardly likely to cause any adverse effect.

   * flyspell.el

     Apply the patch in `patches/flyspell.patch'.

   * mouse-drag.el

     Apply the patch in `patches/mouse-drag.patch'.

   * isearch.el

     This is one complicated mess to dig through.  Better just end the
     search with `<RET>' before toggling and resume with `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.


