~ubuntu-branches/ubuntu/natty/auctex/natty

@ifset rawfile
@include macros.texi

@node Frequently Asked Questions, Introduction to FAQ, (dir), (dir)
@top Frequently Asked Questions about @previewlatex{}

@contents

@end ifset

@menu
* Introduction to FAQ::         
* Requirements::                
* Installation Trouble::        
* Customization::               
@end menu

@comment we need at least one chapter, or the numbers disappear in the
@comment plain version of the FAQ.

@ifset rawfile
@node Introduction to FAQ, Requirements, Frequently Asked Questions, Frequently Asked Questions
@chapter Introduction
@raisesections
@end ifset
@ifclear rawfile
@node Introduction to FAQ, Requirements, Frequently Asked Questions, Frequently Asked Questions
@section Introduction
@end ifclear

@subsection How can I contribute to the FAQ?

Send an email with the subject:
@example
Preview FAQ
@end example
to @email{auctex-devel@@gnu.org}.

@node Requirements, Installation Trouble, Introduction to FAQ, Frequently Asked Questions
@section Requirements

@subsection Which version of (X)Emacs is needed?
See also the table at the end of the section.

@previewlatex{} nominally requires @w{GNU Emacs} with a version of at
least 21.1.  However, @w{Emacs 22} (currently under development) offers
superior performance and wider platform support, and is even now the
recommended platform to use.

While recent versions of @w{XEmacs 21.4} are supported, doing this in a
satisfactory manner has proven to be difficult due to technical
shortcomings and differing API's which are hard to come by.  If
@previewlatex{} is an important part of your editing workflow, you are
likely to get better results and support by switching to Emacs.  Of
course, you can improve support for your favorite editor by giving
feedback in case you encounter bugs.

@subsection Which versions of Ghostscript and @AUCTeX{} are needed?

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

Proper PDF@LaTeX{} support will require @AUCTeX{} version 11.50 or
later.  Versions before that are not supported.

@subsection I have trouble with the display format...
We recommend keeping the variable @code{preview-image-type} set to
@code{dvipng} (if you have it installed) or @code{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
@acronym{PNG}, the proper idea to deal with that is to complain to your
Emacs providers.  Short of that, checking out @acronym{PNM} or
@acronym{JPEG} formats might be a good way to find out whether the lack
of @acronym{PNG} format support might be the only problem with your
Emacs.

@subsection 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
@previewlatex{} 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 @w{Emacs
22} which has not yet been released at the time of this writing.
@acronym{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.

@multitable {Win9x native} {Emacs version} {XEmacs version}
@item OS @tab Emacs version @tab XEmacs version
@item X11/Unix @tab 21.1 @tab 21.4.9
@item Win9x cygwin @tab 21.4? @tab 21.4.8
@item Win9x native @tab 21.4? @tab 21.4.8
@end multitable

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

@node Installation Trouble, Customization, Requirements, Frequently Asked Questions
@section Installation Trouble

@subsection I could not install the precompiled RPM binaries

Note that the binaries require @acronym{RPM} version 3. 


@subsection I just get @samp{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
@file{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:

@table @asis
@item Incompatible @acronym{RPM} installation
The @acronym{RPM} packages are intended to run on a Redhat system. So
the TeX files, provided by package @file{preview-latex-common} go into
@file{/usr/share/texmf/tex/latex/preview} and
@file{/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
@file{preview-latex.spec} accordingly, repack and then use the
appropriate @samp{rpm} command for building @acronym{RPM}s 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.

@item 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.

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

@item An outdated @file{preview} installation
The @file{preview.sty} package is useful for more than just
@previewlatex{}.  For example, it is part of @TeX{}live.  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 @file{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.
@end table

@subsection 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 @file{preview-latex-xemacs}
@acronym{RPM} package are in XEmacs package format and will be installed
right into the XEmacs package tree.  The location is detected when the
RPM file is built.  If it is wrong for your system, doing an
@example
  rpmbuild --rebuild preview-latex-0.9.1-1.fedora.src.rpm
@end example
should do the trick and should generate RPMs for your system (even if
that System happens to be SuSE rather than Fedora).

Alternatively you could install @previewlatex{} manually in your home
directory either in @file{~/.xemacs} (for XEmacs version below 21.4.x)
or in @file{~/.xemacs/xemacs-packages} (for versions starting with
21.4).

@subsection After installation of the XEmacs @acronym{RPM} package, @AUCTeX{} does not work

Most likely you installed the @acronym{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).  Your init file will contain an
invocation of @previewlatex{} according to the installation instructions
in
@ifclear rawfile
@ref{Installation}.
@end ifclear
@ifset rawfile
@file{INSTALL}.
@end ifset

In consequence, the attempt to load @previewlatex{} when entering
@AUCTeX{} mode fails because of @previewlatex{} being in a different
directory, and this @AUCTeX{}'s actication is aborted.  Please notice
that the installation instructions for Emacs and XEmacs differ.

@node Customization,  , Installation Trouble, Frequently Asked Questions
@section Customization

@subsection Why don't I get balloon help like in the screen shots?

Some users have reported problems with their XEmacs version, so balloon
help is no longer switched on by default.  Use the Preview/Customize
menu or @kbd{@key{M-x} customize-variable} in order to customize
@code{preview-use-balloon-help} to `On'.  This only concerns XEmacs:
tooltips under @w{GNU Emacs} are enabled by default and unproblematic.

@subsection How to include additional environments like @code{enumerate}

By default, @previewlatex{} is intended mainly for displaying
mathematical formulas, so environments like @code{enumerate} or
@code{tabular} (except where contained in a float) are not included.
You can include them however manually by adding the lines:

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

in your document header, that is before 

@example
\begin@{document@}
@end example
@noindent
In general, @file{preview} should be loaded as the last thing before
the start of document.

Be aware that

@example
\PreviewEnvironment@{...@}
@end example

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

@example
\PreviewEnvironment@{...@}
@end example

in your document, it will look more and more like a @acronym{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.

@subsection 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 @file{prdefault.cfg} which
is used for any use of the @samp{preview} package, or you can use
@file{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

@example
\InputIfFileExists@{preview/prauctex.cfg@}@{@}@{@}
\PreviewEnvironment@{enumerate@}
@end example

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

@subsection 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 @code{\usepackage} call to
@samp{preview} so that it will be able to interpret its various
definition commands.  It is an error to add the @code{active} option to
this invocation: you don't want the package to be active unless
@previewlatex{} itself enables the previewing operation (which it will).

@subsection 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 @file{preview.sty} to tell it how to resolve this, whether
you want no previews, previews of whole slides or previews of inner
material.

@section Troubleshooting

@subsection 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

@example
! 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.
@end example

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 @strong{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
@example
Preview-LaTeX exited as expected with code 1 at Wed Sep  4 17:03:30
@end example
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 @file{.log} file.

@section @previewlatex{} when not using @LaTeX{}

@subsection Does @previewlatex{} work with  PDF@LaTeX{}?

Yes.  PDF@LaTeX{} works fine with @AUCTeX{} version 11.50 or later.  For
earlier versions, you need to have @code{LaTeX-command-style} configured
manually to call PDF@LaTeX{}.

@subsection Does @previewlatex{} work with @samp{elatex}?

No problem here.  If you configure your @AUCTeX{} to use @samp{elatex},
or simply have @samp{latex} point to @samp{elatex}, this will work fine.

@subsection Does @previewlatex{} work with @ConTeXt{}?

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

@subsection Does @previewlatex{} work with plain TeX?

Again, no.  Restructuring the @samp{preview} package for @samp{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:

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