Introduction
============

How can I contribute to the FAQ?
--------------------------------

Send an email with the subject:

     Preview FAQ

to auctex-devel@gnu.org.

Requirements
============

Which version of (X)Emacs is needed?
------------------------------------

See also the table at the end of the section.

previewlatex nominally requires GNU Emacs with a version of at least 24.1.

Which versions of Ghostscript and AUCTeX are needed?
----------------------------------------------------

We recommend to use GNU or AFPL Ghostscript with a version of at least 7.07.

previewlatex has been distributed as part of AUCTeX since version 11.80.  If your version of AUCTeX is older than that, or if it does not contain a working copy of previewlatex, complain to wherever you got it from.

I have trouble with the display format...
-----------------------------------------

We recommend keeping the variable preview-image-type set to dvipng (if you have it installed) or 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 way to deal with that is to complain to your Emacs provider.  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.

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.

There are several development versions of Emacs around for native MacOS Carbon, and previewlatex is working with them, too.

With Windows, Cygwin should work.

Installation Trouble
====================

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 previewlatex 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:

Filename database not updated
     Various TeX distributions have their own ways of knowing where the files are without actually searching directories.  The normal previewlatex 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, previewlatex 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 previewlatex.  For example, it is part of TeXlive.  So you have to make sure that previewlatex 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 previewlatex 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.

Customization
=============

How to include additional environments like enumerate
-----------------------------------------------------

By default, previewlatex is intended mainly for displaying 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 previewlatex.  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.

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.

Suddenly I get gazillions of ridiculous pages?!?
------------------------------------------------

When previewlatex 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 previewlatex 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 previewlatex itself enables the previewing operation (which it will).

Does previewlatex work with presentation classes?
-------------------------------------------------

previewlatex should work with most presentation classes.  However, since those classes often have macros or pseudo environments encompassing a complete slide, you will need to use the customization facilities of preview.sty to tell it how to resolve this, whether you want no previews, previews of whole slides or previews of inner material.

Troubleshooting
===============

Preview causes all sort of strange error messages
-------------------------------------------------

When running previewlatex 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 previewlatex 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 as expected 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 previewlatex 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.

Why do my DVI and PDF output files vanish?
------------------------------------------

In order to produce the preview images previewlatex runs LaTeX on the master or region file.  The resulting DVI or PDF file can happen to have the same name as the output file of a regular LaTeX run.  So the regular output file gets overwritten and is subsequently deleted by previewlatex.

My output file suddenly only contains preview images?!
------------------------------------------------------

As mentioned in the previews FAQ entry, previewlatex might use the file name of the original output file for the creation of preview images.  If the original output file is being displayed with a viewer when this happens, you might see strange effects depending on the viewer, e.g. a message about the file being corrupted or the display of all the preview images instead of your typeset document.  (Also see Customization.)

previewlatex when not using LaTeX
=================================

Does previewlatex work with PDFLaTeX?
-------------------------------------

Yes, as long as you use AUCTeX's own PDFLaTeX mode and have not messed with TeX-command-list.

Does previewlatex 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. Modern TeX distributions use eTeX for LaTeX, anyway.

Does previewlatex work with ConTeXt?
------------------------------------

In short, no.  The preview package is LaTeX-dependent.  Adding support for other formats requires volunteers.

Does previewlatex 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}