emacs/code/elpa/auctex-13.2.1/doc/preview-problems.texi

@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 with preview-latex

@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
* Font problems with Dvips::    
* Too small bounding boxes::    
* x-symbol interoperation::     
* Middle-clicks paste instead of toggling::  
* No images are displayed with gs 9.27 and earlier::
* Black texts are too hard to read on dark background::
@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 Font problems with Dvips
@chapter Font problems with Dvips
@raisesections
@end ifset
@ifclear rawfile
@node Font problems with Dvips
@section Font problems with Dvips
@end ifclear

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-option @key{RET} preview-fast-dvips-command @key{RET}}
@end display
@noindent
and
@display
@kbd{M-x customize-option @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 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.

@c FIXME: It seems that x-symbol is much outdated.
@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 @samp{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 @samp{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{isearch.el}
is known to be affected 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.

@node No images are displayed with gs 9.27 and earlier
@section No images are displayed with gs 9.27 and earlier

@previewlatex{} tries to adjust the foreground and background colors of
generated images to those of Emacs.  Unfortunately, incompatible changes
introduced in Ghostscript 9.27 breaks the traditional method partially,
and @previewlatex{} can display no images under certain circumstances.

A new method implemented alternatively works only with Ghostscript >
9.27.  If you are using Ghostscript 9.27 or earlier, customize the
option @code{preview-pdf-adjust-color-method}.

@defopt preview-pdf-adjust-color-method
Method to adjust colors of images generated from @acronym{PDF}.  It is
not consulted when the @LaTeX{} command produces @acronym{DVI} files.

When the option is @code{t} (default), @previewlatex{} adjusts the FG
and BG colors of the generated images by the new method.  This method
requires that Ghostscript has working @code{DELAYBIND} feature, thus is
invalid with gs 9.27 (and possibly < 9.27).

When it is @code{compatible}, @previewlatex{} uses traditional method.
This option is provided for backward compatibility with older gs.  See
the below explanation for detail.

When @code{nil}, no adjustment is done and ``black on white'' image is
generated regardless of Emacs color.  This is provided for fallback for
gs 9.27 users with customized foreground color.  See the below
explanation for detail.

When the @LaTeX{} command produces @acronym{PDF} rather than
@acronym{DVI} and Emacs has non-trivial foreground color, the
traditional method (@code{compatible}) makes gs >= 9.27 to stop with
error.  Here, ``non-trivial foreground color'' includes customized
themes.

If you use such non-trivial foreground color and the version of
Ghostscript equals to 9.27, you have two options:
@enumerate
@item
Choose the value @code{compatible} and customize
@code{preview-reference-face} to have default (black) foreground color.
This makes the generated image almost non-readable on dark background,
so the next option would be your only choice in that case.
@item
Choose the value @code{nil}, which forces plain ``black on white''
appearance for the generated image.  You can at least read what are
written in the image although they may not match with your Emacs color
well.
@end enumerate

The default value used to be @code{compatible} for short period before
Ghostscript 9.50 was released but now is @code{t}.
@end defopt

@node Black texts are too hard to read on dark background
@section Black texts are too hard to read on dark background
Unfortunately, foreground color adjustment discussed in the previous node
doesn't work for Xe@LaTeX{} for technical reason.  The texts are always
rendered as black in the preview images, so it's almost impossible to read
them on dark background.  Hence Xe@LaTeX{} users who like dark background
in Emacs frame should customize @code{preview-pdf-adjust-color-method} to
@code{nil}.