3 @c documentencoding is used by makeinfo in our --no-headers output.
4 @documentencoding ISO-8859-1
5 @node Known problems,,(dir),(dir)
9 @c -----------------------
10 @c @cindex @kbd{M-x preview-report-bug @key{RET}}
11 @c @cindex @code{preview-report-bug}
12 @c @cindex Report a bug
13 A number of issues are known concerning the interoperation with various
14 other software. Some of the known problems can be solved by moving to
15 newer versions of the problematic software or by simple patches.
18 * Problems with Ghostscript::
19 * Font problems with Dvips::
21 * Too small bounding boxes::
22 * x-symbol interoperation::
23 * Middle-clicks paste instead of toggling::
26 If you find something not mentioned here, please send a bug report using
27 @kbd{M-x preview-report-bug @key{RET}}, which will fill in a lot of
28 information interesting to us and send it to the
29 @email{bug-auctex@@gnu.org} list. Please use the bug reporting commands
33 @node Problems with Ghostscript
34 @chapter Problems with Ghostscript
38 @node Problems with Ghostscript
39 @section Problems with Ghostscript
42 Most of the problems encountered come from interaction with Ghostscript.
43 It is a good idea to have a fairly recent version of Ghostscript
44 installed. One problem occurs if you have specified the wrong
45 executable under Windows: the command line version of Ghostscript is
46 called @file{GSWIN32C.EXE}, not @file{GSWIN32.EXE}.
48 When Ghostscript fails, the necessary information and messages from
49 Ghostscript go somewhere. If Ghostscript fails before starting to
50 process images, you'll find the information at the end of the process
51 buffer you can see with @kbd{C-c C-l}. If Ghostscript fails while
52 processing a particular image, this image will be tagged with clickable
53 buttons for the error description and for the corresponding source file.
55 The default options configurable with
58 @kbd{M-x customize-variable @key{RET} preview-gs-options @key{RET}}
60 @vindex preview-gs-options
62 include the options @option{-dTextAlphaBits=4} and
63 @option{-dGraphicsAlphaBits=4}. These options have been reported to
64 make Ghostscript 5.50 fail, but should work under Ghostscript 6.51 and
65 later. If you are experiencing problems, it might help to customize
66 them away. Of course, this also takes away the joy of antialiasing, so
67 upgrading Ghostscript might not be the worst idea after all.
69 The device names have changed over time, so when using an old
70 Ghostscript, you may have problems with the devices demanded by the
71 customizable variable @code{preview-image-creators}.
72 @vindex preview-image-creators
73 In that case, make sure they fit your version of Ghostscript, at least
74 the entry corresponding to the current value of
75 @code{preview-image-type}.
76 @vindex preview-image-type
77 While not being best in file size and image quality, setting
78 @code{preview-image-creators} to @code{jpeg} should probably be one of
79 the best bets for the purpose of checking basic operation, since that
80 device name has not changed in quite some time. But @acronym{JPEG} is
81 not intended for text, but for photographic images. On a more
82 permanent time scale, the best choice is to use @acronym{PNG} and
83 complain to your suppliers if either Emacs or Ghostscript fail to
84 properly accommodate this format.
86 @node Font problems with Dvips
87 @section Font problems with Dvips
88 Some fonts have been reported to produce wrong characters with
89 @previewlatex{}. @previewlatex{} calls Dvips by default with the option
90 @option{-Pwww} in order to get scalable fonts for nice results. If you
91 are using antialiasing, however, the results might be sufficiently nice
92 with bitmapped fonts, anyway. You might try @option{-Ppdf} for another
93 stab at scalable fonts, or other printer definitions. Use
96 @kbd{M-x customize-variable @key{RET} preview-fast-dvips-command @key{RET}}
101 @kbd{M-x customize-variable @key{RET} preview-dvips-command @key{RET}}
104 in order to customize this.
106 One particular problem is that several printer setup files (typically in
107 a file called @file{/usr/share/texmf/dvips/config/config.pdf} if you are
108 using the @option{-Ppdf} switch) contain the @option{G} option for
109 `character shifting'. This option will result in @samp{fi} being
110 rendered as @samp{@pounds{}} (British Pounds sign) in several fonts,
111 unless your version of Dvips has a long-standing bug in its
112 implementation fixed (only very recent versions of Dvips have).
115 @section Emacs problems
118 @item GNU Emacs versions
120 Don't use Emacsen older than 21.3 on X11-based systems. On most other
121 systems, you'll need at least @w{Emacs 22.1} or one of the developer
122 versions leading up to it. Details can be found in
124 in the @file{INSTALL} file.
127 @ref{Prerequisites,,,auctex,the @AUCTeX{} manual}.
130 @item Emacsen on Windows operating systems
132 For @w{Emacs 21}, no image support is available in Emacs under Windows.
133 Without images, @previewlatex{} is useless. The current @acronym{CVS}
134 version of Emacs available from
135 @uref{http://savannah.gnu.org/projects/emacs} now supports images
136 including the @acronym{PNG} format, so @w{Emacs 22} should work out of
137 the box once it is released. Precompiled versions are available from
138 @uref{http://crasseux.com/emacs} and @uref{http://nqmacs.sf.net}.
140 For detailed installation instructions for Windows, see
142 the file @file{INSTALL.windows}
145 @ref{Installation under MS Windows,,,auctex,the @AUCTeX{} manual}.
150 There is are two larger problems known with older XEmacs releases. One
151 leads to seriously mispositioned baselines and previews hanging far
152 above other text on the same line. This should be fixed as of
155 The other core bug causes a huge delay when XEmacs's idea of the state of
156 processes (like ghostscript) is wrong, and can lead to nasty spurious
157 error messages. It should be fixed in version 21.4.8.
159 Previews will only remain from one session to the next if you have
160 version 1.81 or above of the @file{edit-utils} package, first released
161 in the 2002-03-12 sumo tarball.
164 @node Too small bounding boxes
165 @section Too small bounding boxes
166 The bounding box of a preview is determined by the @LaTeX{} package
167 using the pure @TeX{} bounding boxes. If there is material extending
168 outside of the @TeX{} box, that material will be missing from the
169 preview image. This happens for the label-showing boxes from
170 the @code{showkeys} package. This particular problem can be
171 circumvented by using the @code{showlabels} option of the preview
174 In general, you should try to fix the problem in the @TeX{} code, like
175 avoiding drawing outside of the picture with PSTricks.
177 One possible remedy is to set
178 @code{preview-fast-conversion} to `Off'
183 (@pxref{The Emacs interface}).
185 The conversion will take more time, but will then use the bounding boxes
186 from @acronym{EPS} files generated by Dvips.
188 Dvips generally does not miss things, but it does not understand
189 PostScript constructs like @code{\resizebox} or @code{\rotate} commands,
190 so will generate rather wrong boxes for those. Dvips can be helped with
191 the @code{psfixbb} package option to preview
196 (@pxref{The LaTeX style file}),
198 which will tag the corners of the included @TeX{} box. This will mostly
199 be convenient for @emph{pure} PostScript stuff like that created by
200 PSTricks, which Dvips would otherwise reserve no space for.
202 @node x-symbol interoperation
203 @section x-symbol interoperation
205 Thanks to the work of Christoph Wedler, starting with version
206 @samp{4.0h/beta} of x-symbol, the line parsing of @AUCTeX{} and
207 @previewlatex{} is fully supported. Earlier versions exhibit problems.
208 However, versions before 4.2.2 will cause a drastic slowdown of
209 @previewlatex{}'s parsing pass, so we don't recommend to use versions
212 If you wonder what x-symbol is, it is a package that transforms various
213 tokens and subscripts to a more readable form while editing and offers a
214 few input methods handy especially for dealing with math. Take a look at
215 @uref{http://x-symbol.sourceforge.net}.
217 x-symbol versions up to 4.5.1-beta at least require an 8bit-clean @TeX{}
218 implementation (meaning that its terminal output should not use
219 @samp{^^}-started escape sequences) for cooperation with
220 @previewlatex{}. Later versions may get along without it, like
221 @previewlatex{} does now.
223 If you experience problems with @file{circ.tex} in connection with both
224 x-symbol and Latin-1 characters, you may need to change your language
225 environment or, as a last resort, customize the variable
226 @code{LaTeX-command-style} by replacing the command @code{latex} with
227 @code{latex -translate-file=cp8bit}.
229 @node Middle-clicks paste instead of toggling
230 @section Middle-clicks paste instead of toggling
232 This is probably the fault of your favorite package. @file{flyspell.el}
233 and @file{mouse-drag.el} are known to be affected in versions before
234 @w{Emacs 21.3}. Upgrade to the most recent version. What version of
235 XEmacs might contain the fixes is unknown.
237 @file{isearch.el} also shows this effect while searches are in progress,
238 but the code is such a complicated mess that no patch is in sight.
239 Better just end the search with @kbd{@key{RET}} before toggling and
240 resume with @kbd{C-s C-s} or similar afterwards. Since previews over
241 the current match will auto-open, anyway, this should not be much of a