preview-latex in a nutshell
***************************

Does your neck hurt from turning between previewer windows and the
source too often? This Elisp/LaTeX package will render your displayed
LaTeX equations right into the editing window where they belong.

   The purpose of preview-latex is to embed LaTeX environments such as
display math or figures into the source buffers.  By mouse-clicking, you
can open the original text.  After editing, another click will just run
the region in question through LaTeX and redisplay the new results.

   If preview-latex has not come in the form of a preinstalled package
for you, consult the `INSTALL' file for installation instructions
(especially, read the Prerequisites section).

Activating preview-latex
========================

   After installation, the package may need to be activated (and
remember to activate AUCTeX too).  In XEmacs, and in any prepackaged
versions worth their salt, activation should be automatic upon
installation.  If this seems not the case, complain to your
installation provider and read on.  You might salvage this by adding
the following activation line to your own `.emacs' file or to a
site-wide initialization file:

     (add-hook 'LaTeX-mode-hook #'LaTeX-preview-setup)

There might still be missing an `autoload' form in which case you would
have to add

     (autoload 'LaTeX-preview-setup "preview")

And in case the directory to which the Elisp files have been installed
is not known to Emacs, a line like

     (add-to-list 'load-path "/WHATEVER/DIRECTORY")

needs to be added as well.

Getting started
===============

   Once activated, preview-latex and its documentation will be
accessible via its menus (note that preview-latex requires AUCTeX to be
loaded).  When you have loaded a LaTeX document (a sample document
`circ.tex' is included in the distribution, but most documents
including math and/or figures should do), you can use its menu or `C-c
C-p C-d' (for `Preview/Document').  Previews will now be generated for
various objects in your document.  You can use the time to take a short
look at the other menu entries and key bindings in the `Preview' menu.
You'll see the previewed objects change into a roadworks sign when
preview-latex has determined just what it is going to preview.  Note
that you can freely navigate the buffer while this is going on.  When
the process is finished you will see the objects typeset in your buffer.

   It is a bad idea, however, to edit the buffer before the roadworks
signs appear, since that is the moment when the correlation between the
original text and the buffer locations gets established.  If the buffer
changes before that point of time, the previews will not be placed where
they belong. If you do want to change some obvious error you just
spotted, we recommend you stop the background process by pressing `C-c
C-k'.

   To see/edit the LaTeX code for a specific object, put the point (the
cursor) on it and press `C-c C-p C-p' (for `Preview/at point').  It
will also do to click with the middle mouse button on the preview.  Now
you can edit the code, and generate a new preview by again pressing
`C-c C-p C-p' (or by clicking with the middle mouse button on the icon
before the edited text).

   If you are using the `desktop' package, previews will remain from
one session to the next as long as you don't kill your buffer.  If you
are using XEmacs, you will probably need to upgrade the package to the
newest one; things are being fixed just as I am writing this.

Basic modes of operation
========================

   preview-latex has a number of methods for generating its graphics.
The configured default uses whatever LaTeX invocation is mapped to
AUCTeX's `%l' command string which can be customized with

     M-x customize-variable RET LaTeX-command-style RET

If this happens to be a call of PDFLaTeX generating PDF output, then
GhostScript will be called directly on the resulting PDF file.  If a
DVI file gets produced, first Dvips and then GhostScript get called.

   The default value does not call PDFLaTeX, so you might want to enter
an association of the string `\`pdftex\'' with `pdflatex' before the
default, so that AUCTeX will call `pdflatex' automatically whenever it
finds a `pdftex' option to a class.

   The image type to be generated by GhostScript can be configured with

     M-x customize-variable RET preview-image-type RET

The default is `png' (the fastest image type).  A special value can be
configured as `dvipng' if you have the `dvipng' program installed.  In
this case, `dvipng' will be used for converting DVI files and
GhostScript (with a `PNG' device) for converting PDF files.  `dvipng'
is much faster than the combination of Dvips and GhostScript and can be
downloaded from the same sites as preview-latex (in fact, it is part of
the CVS archive of preview-latex).

More documentation
==================

   After the installation, documentation in the form of an info manual
will be available.  You can access it with the standalone info reader
with

     info preview-latex

or by pressing `C-h i d m preview-latex <RET>' in Emacs.  Once
preview-latex is activated, you can instead use `C-c C-p <TAB>' (or the
menu entry `Preview/Read documentation').

   Depending on your installation, a printable manual may also be
available in the form of `preview-latex.dvi' or `preview-latex.ps'.

   Detailed documentation for the LaTeX style used for extracting the
preview images is placed in `preview.dvi' in a suitable directory
during installation; on typical teTeX-based systems,

     texdoc preview

will display it.

Availability
============

   The preview-latex project is available at SourceForge.  In addition
to the main source tarball, we provide prebuilt documentation files
there for those lacking a recent enough version of makeinfo, and source
and binary `.rpm' files suitable for a recent RedHat system. Anonymous
CVS is available as well. The SourceForge project page of preview-latex
is `http://sourceforge.net/projects/preview-latex'.

Contacts
========

   Bug reports should be sent by using `M-x preview-report-bug <RET>',
as this will fill in a lot of information interesting to us. If the
installation fails (but this should be a rare event), report bugs to
<preview-latex-bugs@lists.sourceforge.net>.

   Questions, suggestions for new features, pleas for help, and/or
praise should go to <preview-latex-devel@lists.sourceforge.net> (the
preview-latex devel team).  For more information on this mailing list,
send a message with just the word `help' as subject or body to
<preview-latex-devel-request@lists.sourceforge.net> or look at
`http://lists.sourceforge.net/lists/listinfo/preview-latex-devel'.
Please use the command `M-x preview-report-bug <RET>' to report bugs if
possible.

   Offers to support further development will be appreciated.  If you
want to show your appreciation with a donation to the main developer,
you can do so via PayPal to <dakas@users.sourceforge.net>, and of course
you can arrange for service contracts or for added functionality.  Take
a look at the `TODO' list for suggestions in that area.

   For developer access, ask on
<preview-latex-devel@lists.sourceforge.net>.

