1 @c This is part of the preview-latex manual.
2 @c Copyright (C) 2002, 2003, 2004, 2005, 2006, 2009 Free Software
4 @c See file preview-latex.texi for copying conditions.
8 @node Frequently Asked Questions, Introduction to FAQ, (dir), (dir)
9 @top Frequently Asked Questions about @previewlatex{}
16 * Introduction to FAQ::
18 * Installation Trouble::
24 @comment we need at least one chapter, or the numbers disappear in the
25 @comment plain version of the FAQ.
28 @node Introduction to FAQ, Requirements, Frequently Asked Questions, Frequently Asked Questions
33 @node Introduction to FAQ, Requirements, Frequently Asked Questions, Frequently Asked Questions
37 @subsection How can I contribute to the FAQ?
39 Send an email with the subject:
43 to @email{auctex-devel@@gnu.org}.
45 @node Requirements, Installation Trouble, Introduction to FAQ, Frequently Asked Questions
48 @subsection Which version of (X)Emacs is needed?
49 See also the table at the end of the section.
51 @previewlatex{} nominally requires @w{GNU Emacs} with a version of at
52 least 21.1. However, @w{Emacs 22} (currently under development) offers
53 superior performance and wider platform support, and is even now the
54 recommended platform to use.
56 While recent versions of @w{XEmacs 21.4} are supported, doing this in a
57 satisfactory manner has proven to be difficult due to technical
58 shortcomings and differing API's which are hard to come by. If
59 @previewlatex{} is an important part of your editing workflow, you are
60 likely to get better results and support by switching to Emacs. Of
61 course, you can improve support for your favorite editor by giving
62 feedback in case you encounter bugs.
64 @subsection Which versions of Ghostscript and @AUCTeX{} are needed?
66 We recommend to use GNU or AFPL Ghostscript with a version of at least
69 @previewlatex{} has been distributed as part of @AUCTeX{} since version
70 11.80. If your version of @AUCTeX{} is older than that, or if it does
71 not contain a working copy of @previewlatex{}, complain to wherever you
74 @subsection I have trouble with the display format...
75 We recommend keeping the variable @code{preview-image-type} set to
76 @code{dvipng} (if you have it installed) or @code{png}. This is the
77 default and can be set via the Preview/Customize menu.
79 All other formats are known to have inconveniences, either in file size
80 or quality. There are some Emacs versions around not supporting
81 @acronym{PNG}; the proper way to deal with that is to complain to your
82 Emacs provider. Short of that, checking out @acronym{PNM} or
83 @acronym{JPEG} formats might be a good way to find out whether the lack
84 of @acronym{PNG} format support might be the only problem with your
87 @subsection For which OS does preview work?
89 It is known to work under the X Window System for Linux and for several
90 flavors of Unix: we have reports for HP and Solaris.
92 There are several development versions of Emacs around for native MacOS
93 Carbon, and @previewlatex{} is working with them, too.
95 With Windows, Cygwin and native ports of XEmacs should work.
96 @previewlatex{} will not work with any native version 21 of Emacs under
97 Windows: you need to get a hold of @w{Emacs 22} which is at the time of
98 this writing not released but available as a developer snapshot.
100 The entry "X11/Unix" currently means Linux, Solaris or HP/UX, as well as
101 the X-specific version for Mac/OSX.
103 @multitable {Win9x native} {Emacs version} {XEmacs version}
104 @item OS @tab Emacs version @tab XEmacs version
105 @item X11/Unix @tab 21.1 @tab 21.4.9
106 @item Win9x cygwin @tab 21.3.50? @tab 21.4.8
107 @item Win9x native @tab 22.1 @tab 21.4.8
108 @item MacOSX native @tab 22.1 @tab --
111 @node Installation Trouble, Customization, Requirements, Frequently Asked Questions
112 @section Installation Trouble
114 @subsection I just get @samp{LaTeX found no preview images}.
116 The reason for this is that @LaTeX{} found no preview images in the
117 document in question.
119 One reason might be that there are no previews to be seen. If you have
120 not used @previewlatex{} before, you might not know its manner of
121 operation. One sure-fire way to test if you just have a document where
122 no previews are to be found is to use the provided example document
123 @file{circ.tex} (you will have to copy it to some directory where you
124 have write permissions). If the symptom persists, you have a problem,
125 and the problem is most likely a @LaTeX{} problem. Here are possible
130 @item Filename database not updated
131 Various @TeX{} distributions have their own ways of knowing where the
132 files are without actually searching directories. The normal
133 @previewlatex{} installation should detect common tools for that purpose
134 and use them. If this goes wrong, or if the files get installed into a
135 place where they are not looked for, the @LaTeX{} run will fail.
137 @item An incomplete manual installation
138 This should not happen if you followed installation instructions.
139 Unfortunately, people know better all the time. If only
140 @file{preview.sty} gets installed without a set of supplementary files
141 also in the @file{latex} subdirectory, @previewlatex{} runs will not
142 generate any errors, but they will not produce any previews, either.
144 @item An outdated @file{preview} installation
145 The @file{preview.sty} package is useful for more than just
146 @previewlatex{}. For example, it is part of @TeX{}live. So you have
147 to make sure that @previewlatex{} does not get to work with outdated
148 style and configuration files: some newer features will not work with
149 older @TeX{} style files, and really old files will make
150 @previewlatex{} fail completely. There usual is a local @file{texmf}
151 tree, or even a user-specific tree that are searched before the default
152 tree. Make sure that the first version of those files that gets found
156 @subsection I have problems with the XEmacs installation
157 Please note that the XEmacs installation is different, since XEmacs has
158 a package system that gets used here. Please make sure that you read
159 and follow the installation instructions for XEmacs.
161 @node Customization, Troubleshooting, Installation Trouble, Frequently Asked Questions
162 @section Customization
164 @subsection Why don't I get balloon help like in the screen shots?
166 Some users have reported problems with their XEmacs version, so balloon
167 help is no longer switched on by default. Use the Preview/Customize
168 menu or @kbd{@key{M-x} customize-variable} in order to customize
169 @code{preview-use-balloon-help} to `On'. This only concerns XEmacs:
170 tooltips under @w{GNU Emacs} are enabled by default and unproblematic.
172 @subsection How to include additional environments like @code{enumerate}
174 By default, @previewlatex{} is intended mainly for displaying
175 mathematical formulas, so environments like @code{enumerate} or
176 @code{tabular} (except where contained in a float) are not included.
177 You can include them however manually by adding the lines:
180 \usepackage[displaymath,textmath,sections,graphics,floats]@{preview@}
181 \PreviewEnvironment@{enumerate@}
184 in your document header, that is before
190 In general, @file{preview} should be loaded as the last thing before
191 the start of document.
196 \PreviewEnvironment@{...@}
199 does not accept a comma separated
200 list! Also note that by putting more and more
203 \PreviewEnvironment@{...@}
206 in your document, it will look more and more like a @acronym{DVI} file
207 preview when running @previewlatex{}. Since each preview is treated as
208 one large monolithic block by Emacs, one should really restrict
209 previews to those elements where the improvement in visual
210 representation more than makes up for the decreased editability.
212 @subsection What if I don't want to change the document?
213 The easiest way is to generate a configuration file in the current
214 directory. You can basically either create @file{prdefault.cfg} which
215 is used for any use of the @samp{preview} package, or you can use
216 @file{prauctex.cfg} which only applies to the use from with Emacs. Let
217 us assume you use the latter. In that case you should write something like
220 \InputIfFileExists@{preview/prauctex.cfg@}@{@}@{@}
221 \PreviewEnvironment@{enumerate@}
224 in it. The first line inputs the system-wide default configuration
225 (the file name should match that, but not your own
226 @file{prauctex.cfg}), then you add your own stuff.
228 @subsection Suddenly I get gazillions of ridiculous pages?!?
230 When @previewlatex{} works on extracting its stuff, it typesets each
231 single preview on a page of its own. This only happens when actual
232 previews get generated. Now if you want to configure @previewlatex{} in
233 your document, you need to add your own @code{\usepackage} call to
234 @samp{preview} so that it will be able to interpret its various
235 definition commands. It is an error to add the @code{active} option to
236 this invocation: you don't want the package to be active unless
237 @previewlatex{} itself enables the previewing operation (which it will).
239 @subsection Does @previewlatex{} work with presentation classes?
241 @previewlatex{} should work with most presentation classes. However,
242 since those classes often have macros or pseudo environments
243 encompassing a complete slide, you will need to use the customization
244 facilities of @file{preview.sty} to tell it how to resolve this, whether
245 you want no previews, previews of whole slides or previews of inner
248 @node Troubleshooting, Other formats, Customization, Frequently Asked Questions
249 @section Troubleshooting
251 @subsection Preview causes all sort of strange error messages
253 When running @previewlatex{} and taking a look at either log file or
254 terminal output, lots of messages like
257 ! Preview: Snippet 3 started.
260 l.52 \item Sie lassen sich als Funktion $
261 y = f(x)$ darstellen.
262 ! Preview: Snippet 3 ended.(491520+163840x2494310).
265 l.52 \item Sie lassen sich als Funktion $y = f(x)$
269 appear (previous versions generated messages looking even more like
270 errors). Those are not real errors (as will be noted in the log
271 file). Or rather, while they @strong{are} really @TeX{} error
272 messages, they are intentional. This currently is the only reliable
273 way to pass the information from the @LaTeX{} run of @previewlatex{} to
274 its Emacs part about where the previews originated in the source text.
275 Since they are actual errors, you will also get @AUCTeX{} to state
277 Preview-LaTeX exited as expected with code 1 at Wed Sep 4 17:03:30
279 after the @LaTeX{} run in the run buffer. This merely indicates that
280 errors were present, and errors will always be present when
281 @previewlatex{} is operating. There might be also real errors, so in
282 case of doubt, look for them explicitly in either run buffer or the
283 resulting @file{.log} file.
285 @subsection Why do my @acronym{DVI} and @acronym{PDF} output files vanish?
287 In order to produce the preview images @previewlatex{} runs @LaTeX{} on
288 the master or region file. The resulting @acronym{DVI} or @acronym{PDF}
289 file can happen to have the same name as the output file of a regular
290 @LaTeX{} run. So the regular output file gets overwritten and is
291 subsequently deleted by @previewlatex{}.
293 @subsection My output file suddenly only contains preview images?!
295 As mentioned in the previews @acronym{FAQ} entry, @previewlatex{} might
296 use the file name of the original output file for the creation of
297 preview images. If the original output file is being displayed with a
298 viewer when this happens, you might see strange effects depending on the
299 viewer, e.g. a message about the file being corrupted or the display of
300 all the preview images instead of your typeset document. (Also
301 @xref{Customization}.)
304 @node Other formats, , Troubleshooting, Frequently Asked Questions
305 @section @previewlatex{} when not using @LaTeX{}
307 @subsection Does @previewlatex{} work with PDF@LaTeX{}?
309 Yes, as long as you use @AUCTeX{}'s own PDF@LaTeX{} mode and have not
310 messed with @samp{TeX-command-list}.
312 @subsection Does @previewlatex{} work with @samp{elatex}?
314 No problem here. If you configure your @AUCTeX{} to use @samp{elatex},
315 or simply have @samp{latex} point to @samp{elatex}, this will work fine.
316 Modern @TeX{} distributions use e@TeX{} for @LaTeX{}, anyway.
318 @subsection Does @previewlatex{} work with @ConTeXt{}?
320 In short, no. The @samp{preview} package is
321 @LaTeX{}-dependent. Adding support for other formats requires
324 @subsection Does @previewlatex{} work with plain TeX?
326 Again, no. Restructuring the @samp{preview} package for @samp{plain}
327 operation would be required. Volunteers welcome.
329 In some cases you might get around by making a wrapper pseudo-Master
330 file looking like the following:
333 \documentclass@{article@}