Frequently Asked Questions about preview-latex
**********************************************


...Table of Contents...
1 Introduction
**************

1.1 How can I contribute to the FAQ?
====================================

   Send an email with the subject:
     Preview FAQ
   to Uwe Brauer <oub@eucmos.sim.ucm.es>.

2 Requirements
**************

2.1 Which version of (X)Emacs is needed?
========================================

   See also the table at the end of the section.

   preview-latex requires explicitely GNU Emacs with a version of at
least 21.1. Concerning XEmacs, it is reported that it works for versions
starting with 21.1.14 (with and without Mule). It is not expected to
work with any with any version prior to this.  The operation of
versions before 21.4.9 suffers from some `cosmetic' problems:

2.2 Display Problem in XEmacs
=============================

   Vertical constructs such as superscripts are not displayed correctly
in XEmacs. This is a known bug of the XEmacs display engine and
supposed to be solved in version 21.4.9 for the X Window System
version.  For MS Windows, this bug has been fixed in 21.4.8.

2.3 Which versions of GhostScript and AUCTeX are needed?
========================================================

   We recommend to use GNU or AFPL GhostScript with a version of at
least 6.51.  Versions above 7.xx have better antialiasing.

   We also recommend strongly to use at least AUCTeX-11.14. Versions
prior to that may work but are known to cause problems with multiple
directories, as well as with detection of text locations for previews
generated by partial TeX compilations.  The latter problem can be
patched for version 10.0g, see the `patches' directory of the
preview-latex distribution.

2.4 I have trouble with the display format...
=============================================

   We recommend keeping the variable `preview-image-type' set to `png'.
This is the default and can be set via the Preview/Customize menu.

   All other formats are known to have inconveniences, either in file
size or quality.  There are some Emacs versions around not supporting
PNG, the proper idea to deal with that is to complain to your Emacs
providers.  Short of that, checking out PNM or JPEG formats might be a
good way to find out whether the lack of PNG format support might be
the only problem with your Emacs.

2.5 For which OS does preview work?
===================================

   It is known to work under the X Window System for Linux and for
several flavors of Unix: we have reports for HP and Solaris.

   Under Windows, you should try the most recent versions of
preview-latex since a lot of typical Windows problems have been ironed
out lately.  Under XEmacs, both Cygwin and native ports should work.
Image support for GNU Emacs under Windows is expected with Emacs 21.4
which has not yet been released at the time of this writing.  CVS
versions of it already work, however.

   The entry "X11/Unix" currently means Linux, Solaris or HP/UX, as well
as the X-specific version for Mac/OSX.

OS             Emacs version   XEmacs version
X11/Unix       21.1            21.4.9
Win9x cygwin   21.4?           21.4.8
Win9x native   21.4?           21.4.8

   With display errors, XEmacs versions as early as 21.1.14 might also
work.

3 Installation Trouble
**********************

3.1 I could not install the precompiled RPM binaries
====================================================

   Note that the binaries require RPM version 3.

3.2 I just get `LaTeX found no preview images'.
===============================================

   The reason for this is that LaTeX found no preview images in the
document in question.

   One reason might be that there are no previews to be seen.  If you
have not used preview-latex before, you might not know its manner of
operation.  One sure-fire way to test if you just have a document where
no previews are to be found is to use the provided example document
`circ.tex' (you will have to copy it to some directory where you have
write permissions).  If the symptom persists, you have a problem, and
the problem is most likely a LaTeX problem.  Here are possible reasons:

Incompatible RPM installation
     The RPM packages are intended to run on a Redhat system. So the
     TeX files, provided by package `preview-latex-common' go into
     `/usr/share/texmf/tex/latex/preview' and
     `/usr/share/texmf/doc/latex/styles/preview'. If for your system the
     TeX files are in different places you have to set appropriate
     links.

     Another possibility is to get the tar archive, edit the
     `preview-latex.spec' accordingly, repack and then use the
     appropriate `rpm' command for building RPMs from a tar archive.
     If this works, please don't forget to send us the spec file, so
     that we may be able to help others with your platform.

Filename database not updated
     Various TeX distributions have their own ways of knowing where the
     files are without actually searching directories.  The normal
     preview-latex installation should detect common tools for that
     purpose and use them.  If this goes wrong, or if the files get
     installed into a place where they are not looked for, the LaTeX
     run will fail.

An incomplete manual installation
     This should not happen if you followed installation instructions.
     Unfortunately, people know better all the time.  If only
     `preview.sty' gets installed without a set of supplementary files
     also in the `latex' subdirectory, preview-latex runs will not
     generate any errors, but they will not produce any previews,
     either.

An outdated `preview' installation
     The `preview.sty' package is useful for more than just
     preview-latex.  For example, it is part of TeXlive.  So you have
     to make sure that preview-latex does not get to work with outdated
     style and configuration files: some newer features will not work
     with older TeX style files, and really old files will make
     preview-latex fail completely.  There usual is a local `texmf'
     tree, or even a user-specific tree that are searched before the
     default tree.  Make sure that the first version of those files
     that gets found is the correct one.

3.3 I have problems with the XEmacs installation
================================================

   Please note that the XEmacs installation is different, since XEmacs
has a package system that gets used here.  Please make sure that you
read and follow the installation instructions for XEmacs.

   The XEmacs Lisp files provided by the `preview-latex-xemacs' RPM
package are in XEmacs package format and will be installed in
`/usr/lib/xemacs/site-packages'. If on your system the Lisp files are
in different places, you have to set appropriate links.

   Alternatively you could install them locally in your home directory
either in `~/.xemacs' (for XEmacs version below 21.4.x) or in
`~/.xemacs/xemacs-packages' (for versions starting with 21.4).

3.4 After installation of the XEmacs RPM package, AUCTeX does not work
======================================================================

   Most likely you installed the RPM files and you have an XEmacs
version which uses a different architecture of directories, (SuSE is
known to have a no standard architecture, besides it changes it from
SuSE version to SuSE version). Additionally you have set in your init
file an invocation of preview-latex according to the installation
instructions in `INSTALL'.

   Since those demand the loading of preview-latex when entering an
AUCTeX mode, but the load fails because of preview-latex being in a
different directory, this will make turning on an AUCTeX mode fail.
Please notice that the installation instructions for Emacs and XEmacs
differ.  Please follow the respective installation instructions to the
letter unless you know perfectly what you are doing.

4 Customization
***************

4.1 How can I deactivate the annoying balloon mode?
===================================================

   Use the Preview/Customize menu or `<M-x> customize-variable' in
order to customize `preview-use-balloon-help' to `Off'.  This only
concerns XEmacs: tooltips under GNU Emacs can't be disabled, and are
less bothersome, anyhow.

4.2 How to include additionally environments like `enumerate'
=============================================================

   Per default, preview-latex mathematical formulas, so environments
like `enumerate' or `tabular' (except where contained in a float) are
not included.  You can include them however manually by adding the
lines:

     \usepackage[displaymath,textmath,sections,graphics,floats]{preview}
     \PreviewEnvironment{enumerate}

   in your document header, that is before

     \begin{document}

In general, `preview' should be loaded as the last thing before the
start of document.

   Be aware that

     \PreviewEnvironment{...}

   does not accept a comma separated list!  Also note that by putting
more and more

     \PreviewEnvironment{...}

   in your document, it will look more and more like a DVI file preview
when running preview-latex.  Since each preview is treated as one large
monolithic block by Emacs, one should really restrict previews to those
elements where the improvement in visual representation more than makes
up for the decreased editability.

4.3 What if I don't want to change the document?
================================================

   The easiest way is to generate a configuration file in the current
directory.  You can basically either create `prdefault.cfg' which is
used for any use of the `preview' package, or you can use
`prauctex.cfg' which only applies to the use from with Emacs.  Let us
assume you use the latter.  In that case you should write something like

     \InputIfFileExists{preview/prauctex.cfg}{}{}
     \PreviewEnvironment{enumerate}

   in it.  The first line inputs the system-wide default configuration
(the file name should match that, but not your own `prauctex.cfg'),
then you add your own stuff.

4.4 Suddenly I get gazillions of ridiculous pages?!?
====================================================

   When preview-latex works on extracting its stuff, it typesets each
single preview on a page of its own.  This only happens when actual
previews get generated.  Now if you want to configure preview-latex in
your document, you need to add your own `\usepackage' call to `preview'
so that it will be able to interpret its various definition commands.
It is an error to add the `active' option to this invocation: you don't
want the package to be active unless preview-latex itself enables the
previewing operation (which it will).

4.5 Does preview-latex work with presentation classes?
======================================================

   Version 0.7.3 works with the `slides', `foils' and `seminar'
classes.  Earlier versions failed with the `seminar' class and derived
classes (such as `prosper') because they failed to take the
magnification settings of the class into account.

   Since preview-latex does not yet support PDFLaTeX, presentation
packages like `pdfscreen' and `pdfslides' will not yet work.

   Texpower appears to work.

5 Troubleshooting
*****************

5.1 preview-latex does not work with package `xy'
=================================================

   Actually, text math fails to get previewed.  The reason is that the
package `xy' fiddles around with the `$' character at
`\begin{document}' time, at which time it reverts the changes
preview-latex has done to it.  A similar battle of "who will be last?"
is known from packages like `hyperref'.  This particular batte can be
won by loading `preview' by hand, *after* `xy', and specifying the
`delayed' option to it.  That way it gets its changes in after those of
`xy'.

   In short:
     \usepackage[all]{xy}
     \usepackage[textmath,displaymath,floats,graphics,delayed]{preview}

5.2 Preview causes all sort of strange error messages
=====================================================

   When running preview-latex and taking a look at either log file or
terminal output, lots of messages like

     ! Preview: Snippet 3 started.
     <-><->
     
     l.52 \item Sie lassen sich als Funktion $
                                              y = f(x)$ darstellen.
     ! Preview: Snippet 3 ended.(491520+163840x2494310).
     <-><->
     
     l.52 \item Sie lassen sich als Funktion $y = f(x)$
                                                        darstellen.

   appear (previous versions generated messages looking even more like
errors).  Those are not real errors (as will be noted in the log file).
Or rather, while they *are* really TeX error messages, they are
intentional.  This currently is the only reliable way to pass the
information from the LaTeX run of preview-latex to its Emacs part about
where the previews originated in the source text.  Since they are
actual errors, you will also get AUCTeX to state
     Preview-LaTeX exited abnormally with code 1 at Wed Sep  4 17:03:30
   after the LaTeX run in the run buffer.  This merely indicates that
errors were present, and errors will always be present when
preview-latex is operating.  There might be also real errors, so in
case of doubt, look for them explicitly in either run buffer or the
resulting `.log' file.

6 preview-latex when not using LaTeX
************************************

6.1 Does preview-latex work with  PDFLaTeX?
===========================================

   Currently not. This might change in future releases though.  The
usual "volunteers welcome" applies here.  AUCTeX does not handle
PDFLaTeX too well in version 11.11, either.  If you have configured
AUCTeX to call PDFLaTeX by default, for the sake of previewing a normal
LaTeX will be substituted starting with preview-latex 0.7.4.  Together
with packages like `ifpdf.sty' documents which run reasonably well
under both PDFLaTeX as well as LaTeX can be created, making it possible
to use preview-latex on them.

6.2 Does preview-latex work with `elatex'?
==========================================

   No problem here.  If you configure your AUCTeX to use `elatex', or
simply have `latex' point to `elatex', this will work fine.

6.3 Does preview-latex work with ConTeXt?
=========================================

   In short, no.  Currently three obstacles: the `preview' package is
LaTeX-dependent, AUCTeX is required for preview-latex operation but
does not support ConTeXt, and PDFLaTeX is not supported yet.  The last
two obstacles might be removed at some time (preview-latex should
become independent of AUCTeX, and PDFLaTeX will get supported), but the
first again requires volunteer work.

6.4 Does preview-latex work with plain TeX?
===========================================

   Again, no.  Restructuring the `preview' package for `plain'
operation would be required.  Volunteers welcome.

   In some cases you might get around by making a wrapper pseudo-Master
file looking like the following:

     \documentclass{article}
     \usepackage{plain}
     \begin{document}
     \begin{plain}
     \input myplainfile
     \end{plain}
     \end{document}

