code.delx.au - gnu-emacs-elpa/blob - packages/auctex/doc/preview-problems.texi

   1 @include macros.texi
   2 @ifset rawfile
   3 @c documentencoding is used by makeinfo in our --no-headers output.
   4 @documentencoding ISO-8859-1
   5 @node Known problems,,(dir),(dir)
   6 @top Known problems
   7
   8 @end ifset
   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.
  16
  17 @menu
  18 * Problems with Ghostscript::
  19 * Font problems with Dvips::
  20 * Emacs problems::
  21 * Too small bounding boxes::
  22 * x-symbol interoperation::
  23 * Middle-clicks paste instead of toggling::
  24 @end menu
  25
  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
  30 if at all possible.
  31
  32 @ifset rawfile
  33 @node Problems with Ghostscript
  34 @chapter Problems with Ghostscript
  35 @raisesections
  36 @end ifset
  37 @ifclear rawfile
  38 @node Problems with Ghostscript
  39 @section Problems with Ghostscript
  40 @end ifclear
  41
  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}.
  47
  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.
  54
  55 The default options configurable with
  56
  57 @display
  58 @kbd{M-x customize-variable @key{RET} preview-gs-options @key{RET}}
  59 @end display
  60 @vindex preview-gs-options
  61 @noindent
  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.
  68
  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.
  85
  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
  94
  95 @display
  96 @kbd{M-x customize-variable @key{RET} preview-fast-dvips-command @key{RET}}
  97 @end display
  98 @noindent
  99 and
 100 @display
 101 @kbd{M-x customize-variable @key{RET} preview-dvips-command @key{RET}}
 102 @end display
 103 @noindent
 104 in order to customize this.
 105
 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).
 113
 114 @node Emacs problems
 115 @section Emacs problems
 116
 117 @itemize @bullet
 118 @item GNU Emacs versions
 119
 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
 123 @ifset rawfile
 124 in the @file{INSTALL} file.
 125 @end ifset
 126 @ifclear rawfile
 127 @ref{Prerequisites,,,auctex,the @AUCTeX{} manual}.
 128 @end ifclear
 129
 130 @item Emacsen on Windows operating systems
 131
 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}.
 139
 140 For detailed installation instructions for Windows, see
 141 @ifset rawfile
 142 the file @file{INSTALL.windows}
 143 @end ifset
 144 @ifclear rawfile
 145 @ref{Installation under MS Windows,,,auctex,the @AUCTeX{} manual}.
 146 @end ifclear
 147
 148 @item XEmacs
 149
 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
 153 XEmacs-21.4.9.
 154
 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.
 158
 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.
 162 @end itemize
 163
 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
 172 package.
 173
 174 In general, you should try to fix the problem in the @TeX{} code, like
 175 avoiding drawing outside of the picture with PSTricks.
 176
 177 One possible remedy is to set
 178 @code{preview-fast-conversion} to `Off'
 179 @ifset rawfile
 180 (see the manual).
 181 @end ifset
 182 @ifclear rawfile
 183 (@pxref{The Emacs interface}).
 184 @end ifclear
 185 The conversion will take more time, but will then use the bounding boxes
 186 from @acronym{EPS} files generated by Dvips.
 187
 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
 192 @ifset rawfile
 193 (see the manual),
 194 @end ifset
 195 @ifclear rawfile
 196 (@pxref{The LaTeX style file}),
 197 @end ifclear
 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.
 201
 202 @node x-symbol interoperation
 203 @section x-symbol interoperation
 204
 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
 210 earlier than that.
 211
 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}.
 216
 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.
 222
 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}.
 228
 229 @node Middle-clicks paste instead of toggling
 230 @section Middle-clicks paste instead of toggling
 231
 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.
 236
 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
 242 problem in practice.