4
@node Frequently Asked Questions, Introduction to FAQ, (dir), (dir)
5
@top Frequently Asked Questions about @previewlatex{}
12
* Introduction to FAQ::
14
* Installation Trouble::
18
@comment we need at least one chapter, or the numbers disappear in the
19
@comment plain version of the FAQ.
22
@node Introduction to FAQ, Requirements, Frequently Asked Questions, Frequently Asked Questions
27
@node Introduction to FAQ, Requirements, Frequently Asked Questions, Frequently Asked Questions
31
@subsection How can I contribute to the FAQ?
33
Send an email with the subject:
37
to @email{auctex-devel@@gnu.org}.
39
@node Requirements, Installation Trouble, Introduction to FAQ, Frequently Asked Questions
42
@subsection Which version of (X)Emacs is needed?
43
See also the table at the end of the section.
45
@previewlatex{} nominally requires @w{GNU Emacs} with a version of at
46
least 21.1. However, @w{Emacs 22} (currently under development) offers
47
superior performance and wider platform support, and is even now the
48
recommended platform to use.
50
While recent versions of @w{XEmacs 21.4} are supported, doing this in a
51
satisfactory manner has proven to be difficult due to technical
52
shortcomings and differing API's which are hard to come by. If
53
@previewlatex{} is an important part of your editing workflow, you are
54
likely to get better results and support by switching to Emacs. Of
55
course, you can improve support for your favorite editor by giving
56
feedback in case you encounter bugs.
58
@subsection Which versions of Ghostscript and @AUCTeX{} are needed?
60
We recommend to use GNU or AFPL Ghostscript with a version of at least
63
Proper PDF@LaTeX{} support will require @AUCTeX{} version 11.50 or
64
later. Versions before that are not supported.
66
@subsection I have trouble with the display format...
67
We recommend keeping the variable @code{preview-image-type} set to
68
@code{dvipng} (if you have it installed) or @code{png}. This is the
69
default and can be set via the Preview/Customize menu.
71
All other formats are known to have inconveniences, either in file size
72
or quality. There are some Emacs versions around not supporting
73
@acronym{PNG}, the proper idea to deal with that is to complain to your
74
Emacs providers. Short of that, checking out @acronym{PNM} or
75
@acronym{JPEG} formats might be a good way to find out whether the lack
76
of @acronym{PNG} format support might be the only problem with your
79
@subsection For which OS does preview work?
81
It is known to work under the X Window System for Linux and for several
82
flavors of Unix: we have reports for HP and Solaris.
84
Under Windows, you should try the most recent versions of
85
@previewlatex{} since a lot of typical Windows problems have been ironed
86
out lately. Under XEmacs, both Cygwin and native ports should work.
87
Image support for GNU Emacs under Windows is expected with @w{Emacs
88
22} which has not yet been released at the time of this writing.
89
@acronym{CVS} versions of it already work, however.
91
The entry "X11/Unix" currently means Linux, Solaris or HP/UX, as well
92
as the X-specific version for Mac/OSX.
94
@multitable {Win9x native} {Emacs version} {XEmacs version}
95
@item OS @tab Emacs version @tab XEmacs version
96
@item X11/Unix @tab 21.1 @tab 21.4.9
97
@item Win9x cygwin @tab 21.4? @tab 21.4.8
98
@item Win9x native @tab 21.4? @tab 21.4.8
101
With display errors, XEmacs versions as early as 21.1.14 might also work.
103
@node Installation Trouble, Customization, Requirements, Frequently Asked Questions
104
@section Installation Trouble
106
@subsection I could not install the precompiled RPM binaries
108
Note that the binaries require @acronym{RPM} version 3.
111
@subsection I just get @samp{LaTeX found no preview images}.
113
The reason for this is that @LaTeX{} found no preview images in the
114
document in question.
116
One reason might be that there are no previews to be seen. If you have
117
not used @previewlatex{} before, you might not know its manner of
118
operation. One sure-fire way to test if you just have a document where
119
no previews are to be found is to use the provided example document
120
@file{circ.tex} (you will have to copy it to some directory where you
121
have write permissions). If the symptom persists, you have a problem,
122
and the problem is most likely a @LaTeX{} problem. Here are possible
126
@item Incompatible @acronym{RPM} installation
127
The @acronym{RPM} packages are intended to run on a Redhat system. So
128
the TeX files, provided by package @file{preview-latex-common} go into
129
@file{/usr/share/texmf/tex/latex/preview} and
130
@file{/usr/share/texmf/doc/latex/styles/preview}. If for your system the
131
TeX files are in different places you have to set appropriate links.
133
Another possibility is to get the tar archive, edit the
134
@file{preview-latex.spec} accordingly, repack and then use the
135
appropriate @samp{rpm} command for building @acronym{RPM}s from a tar
136
archive. If this works, please don't forget to send us the spec file,
137
so that we may be able to help others with your platform.
139
@item Filename database not updated
140
Various @TeX{} distributions have their own ways of knowing where the
141
files are without actually searching directories. The normal
142
@previewlatex{} installation should detect common tools for that purpose
143
and use them. If this goes wrong, or if the files get installed into a
144
place where they are not looked for, the @LaTeX{} run will fail.
146
@item An incomplete manual installation
147
This should not happen if you followed installation instructions.
148
Unfortunately, people know better all the time. If only
149
@file{preview.sty} gets installed without a set of supplementary files
150
also in the @file{latex} subdirectory, @previewlatex{} runs will not
151
generate any errors, but they will not produce any previews, either.
153
@item An outdated @file{preview} installation
154
The @file{preview.sty} package is useful for more than just
155
@previewlatex{}. For example, it is part of @TeX{}live. So you have
156
to make sure that @previewlatex{} does not get to work with outdated
157
style and configuration files: some newer features will not work with
158
older @TeX{} style files, and really old files will make
159
@previewlatex{} fail completely. There usual is a local @file{texmf}
160
tree, or even a user-specific tree that are searched before the default
161
tree. Make sure that the first version of those files that gets found
165
@subsection I have problems with the XEmacs installation
166
Please note that the XEmacs installation is different, since XEmacs has
167
a package system that gets used here. Please make sure that you read
168
and follow the installation instructions for XEmacs.
170
The XEmacs Lisp files provided by the @file{preview-latex-xemacs}
171
@acronym{RPM} package are in XEmacs package format and will be installed
172
right into the XEmacs package tree. The location is detected when the
173
RPM file is built. If it is wrong for your system, doing an
175
rpmbuild --rebuild preview-latex-0.9.1-1.fedora.src.rpm
177
should do the trick and should generate RPMs for your system (even if
178
that System happens to be SuSE rather than Fedora).
180
Alternatively you could install @previewlatex{} manually in your home
181
directory either in @file{~/.xemacs} (for XEmacs version below 21.4.x)
182
or in @file{~/.xemacs/xemacs-packages} (for versions starting with
185
@subsection After installation of the XEmacs @acronym{RPM} package, @AUCTeX{} does not work
187
Most likely you installed the @acronym{RPM} files and you have an XEmacs
188
version which uses a different architecture of directories, (SuSE is
189
known to have a no standard architecture, besides it changes it from
190
SuSE version to SuSE version). Your init file will contain an
191
invocation of @previewlatex{} according to the installation instructions
200
In consequence, the attempt to load @previewlatex{} when entering
201
@AUCTeX{} mode fails because of @previewlatex{} being in a different
202
directory, and this @AUCTeX{}'s actication is aborted. Please notice
203
that the installation instructions for Emacs and XEmacs differ.
205
@node Customization, , Installation Trouble, Frequently Asked Questions
206
@section Customization
208
@subsection Why don't I get balloon help like in the screen shots?
210
Some users have reported problems with their XEmacs version, so balloon
211
help is no longer switched on by default. Use the Preview/Customize
212
menu or @kbd{@key{M-x} customize-variable} in order to customize
213
@code{preview-use-balloon-help} to `On'. This only concerns XEmacs:
214
tooltips under @w{GNU Emacs} are enabled by default and unproblematic.
216
@subsection How to include additional environments like @code{enumerate}
218
By default, @previewlatex{} is intended mainly for displaying
219
mathematical formulas, so environments like @code{enumerate} or
220
@code{tabular} (except where contained in a float) are not included.
221
You can include them however manually by adding the lines:
224
\usepackage[displaymath,textmath,sections,graphics,floats]@{preview@}
225
\PreviewEnvironment@{enumerate@}
228
in your document header, that is before
234
In general, @file{preview} should be loaded as the last thing before
235
the start of document.
240
\PreviewEnvironment@{...@}
243
does not accept a comma separated
244
list! Also note that by putting more and more
247
\PreviewEnvironment@{...@}
250
in your document, it will look more and more like a @acronym{DVI} file
251
preview when running @previewlatex{}. Since each preview is treated as
252
one large monolithic block by Emacs, one should really restrict
253
previews to those elements where the improvement in visual
254
representation more than makes up for the decreased editability.
256
@subsection What if I don't want to change the document?
257
The easiest way is to generate a configuration file in the current
258
directory. You can basically either create @file{prdefault.cfg} which
259
is used for any use of the @samp{preview} package, or you can use
260
@file{prauctex.cfg} which only applies to the use from with Emacs. Let
261
us assume you use the latter. In that case you should write something like
264
\InputIfFileExists@{preview/prauctex.cfg@}@{@}@{@}
265
\PreviewEnvironment@{enumerate@}
268
in it. The first line inputs the system-wide default configuration
269
(the file name should match that, but not your own
270
@file{prauctex.cfg}), then you add your own stuff.
272
@subsection Suddenly I get gazillions of ridiculous pages?!?
274
When @previewlatex{} works on extracting its stuff, it typesets each
275
single preview on a page of its own. This only happens when actual
276
previews get generated. Now if you want to configure @previewlatex{} in
277
your document, you need to add your own @code{\usepackage} call to
278
@samp{preview} so that it will be able to interpret its various
279
definition commands. It is an error to add the @code{active} option to
280
this invocation: you don't want the package to be active unless
281
@previewlatex{} itself enables the previewing operation (which it will).
283
@subsection Does @previewlatex{} work with presentation classes?
285
@previewlatex{} should work with most presentation classes. However,
286
since those classes often have macros or pseudo environments
287
encompassing a complete slide, you will need to use the customization
288
facilities of @file{preview.sty} to tell it how to resolve this, whether
289
you want no previews, previews of whole slides or previews of inner
292
@section Troubleshooting
294
@subsection Preview causes all sort of strange error messages
296
When running @previewlatex{} and taking a look at either log file or
297
terminal output, lots of messages like
300
! Preview: Snippet 3 started.
303
l.52 \item Sie lassen sich als Funktion $
304
y = f(x)$ darstellen.
305
! Preview: Snippet 3 ended.(491520+163840x2494310).
308
l.52 \item Sie lassen sich als Funktion $y = f(x)$
312
appear (previous versions generated messages looking even more like
313
errors). Those are not real errors (as will be noted in the log
314
file). Or rather, while they @strong{are} really @TeX{} error
315
messages, they are intentional. This currently is the only reliable
316
way to pass the information from the @LaTeX{} run of @previewlatex{} to
317
its Emacs part about where the previews originated in the source text.
318
Since they are actual errors, you will also get @AUCTeX{} to state
320
Preview-LaTeX exited as expected with code 1 at Wed Sep 4 17:03:30
322
after the @LaTeX{} run in the run buffer. This merely indicates that
323
errors were present, and errors will always be present when
324
@previewlatex{} is operating. There might be also real errors, so in
325
case of doubt, look for them explicitly in either run buffer or the
326
resulting @file{.log} file.
328
@section @previewlatex{} when not using @LaTeX{}
330
@subsection Does @previewlatex{} work with PDF@LaTeX{}?
332
Yes. PDF@LaTeX{} works fine with @AUCTeX{} version 11.50 or later. For
333
earlier versions, you need to have @code{LaTeX-command-style} configured
334
manually to call PDF@LaTeX{}.
336
@subsection Does @previewlatex{} work with @samp{elatex}?
338
No problem here. If you configure your @AUCTeX{} to use @samp{elatex},
339
or simply have @samp{latex} point to @samp{elatex}, this will work fine.
341
@subsection Does @previewlatex{} work with @ConTeXt{}?
343
In short, no. The @samp{preview} package is
344
@LaTeX{}-dependent. Adding support for other formats requires
347
@subsection Does @previewlatex{} work with plain TeX?
349
Again, no. Restructuring the @samp{preview} package for @samp{plain}
350
operation would be required. Volunteers welcome.
352
In some cases you might get around by making a wrapper pseudo-Master
353
file looking like the following:
356
\documentclass@{article@}
added
removed
doc/preview-faq.texi
