summaryrefslogtreecommitdiff
path: root/elpa/auctex-13.1.3/doc/preview-problems.texi
diff options
context:
space:
mode:
Diffstat (limited to 'elpa/auctex-13.1.3/doc/preview-problems.texi')
-rw-r--r--elpa/auctex-13.1.3/doc/preview-problems.texi196
1 files changed, 196 insertions, 0 deletions
diff --git a/elpa/auctex-13.1.3/doc/preview-problems.texi b/elpa/auctex-13.1.3/doc/preview-problems.texi
new file mode 100644
index 0000000..e40ff42
--- /dev/null
+++ b/elpa/auctex-13.1.3/doc/preview-problems.texi
@@ -0,0 +1,196 @@
+@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::
+@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