Known problems with preview-latex
*********************************

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 and send it to the <bug-auctex@gnu.org>
list.  Please use the bug reporting commands if at all possible.

1 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).

2 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 'showkeys' package.  This
particular problem can be circumvented by using the '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 'preview-fast-conversion' to 'Off' (see
the manual).  The conversion will take more time, but will then use the
bounding boxes from 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.

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

   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
'^^'-started escape sequences) for cooperation with preview-latex.
Later versions may get along without it, like preview-latex does now.

   If you experience problems with '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
'LaTeX-command-style' by replacing the command 'latex' with 'latex
-translate-file=cp8bit'.

4 Middle-clicks paste instead of toggling
*****************************************

This is probably the fault of your favorite package.  'flyspell.el' and
'mouse-drag.el' are known to be affected in versions before Emacs 21.3.
Upgrade to the most recent version.  What version of XEmacs might
contain the fixes is unknown.

   '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 '<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 in
practice.
