Installing preview-latex should be simple: merely `./configure',
`make', and `make install'.  Note that unlike most emacs add-ins,
preview-latex consists of a TeX part and an Emacs part (that uses
AUC TeX).  This makes configuration a bit trickier than normal.  Please
read through this document fully before installing anything.

Prerequisites
=============

   * A recent version of Emacs 21

     The first version without known quirks and bugs affecting
     preview-latex is Emacs-21.1.  Only very recent pretest versions
     before that have slight chances of working at all.  Since
     preview-latex heavily exercises new features of Emacs 21, getting
     the newest release is a good idea.

   * A working AUC TeX installation

     You need a working AUC TeX installation.  AUC TeX can be found at
     `http://mirrors.sunsite.dk/auctex/www/auctex/'.  All fairly recent
     versions should work.  Since at the time of this writing, the
     latest released version is 10.0g (with known issues), you should
     rather get an alpha test version.  11.11 is known to work well.
     If this option is not available to you, try the patch described in
     the `PROBLEMS' file or *Note Known problems::).

   * A working LaTeX installation

     Preview should work with nearly any LaTeX installation which
     contains dvips, though most testing has taken place using
     tetex-based distributions.

   * A recent GhostScript

     This is not really needed to _install_ the package, but will be
     required for stable operation of it.  Most problems we have
     encountered come from interaction with not so recent versions of
     GhostScript, so it is a good idea to have, say GhostScript 6.51 or
     later installed.

   * The `texinfo' package

     This is needed for building the documentation.  At least
     version 4.0 is required.  If you don't have this, you may download
     a separate tar file with the prebuilt documentation from
     Sourceforge and install it over the main unpacked tar archive.

Configure
=========

   The first step is to configure the source code, telling it where
various files will be.  To do so, run

     ./configure OPTIONS

   (Note: if you have fetched preview-latex from CVS rather than a
regular release, you will have to first generate `./configure' by
running `autogen.sh' in the preview directory.)

   On many machines, you will not need to specify any options, but if
configure cannot determine something on its own, you'll need to help it
out with one of these options

`--with-emacs=/path/to/emacs'
     If you are using a pretest which isn't in your `$PATH', or
     `configure' is not finding the right emacs binary, you can specify
     it with this option.

`--with-tex-site=/dir'
     If AUC TeX is installed in a non-standard location (not in
     `site-lisp'), use this option to specify the location of its
     `tex-site.el' file.

`--with-texmf=/dir
     --with-preview-dir=/dir'
     Both of these options can be used to specify the location to
     install the preview TeX files.  They are not necessary for most
     TeX installs, but may be used if you don't like the directory that
     configure is suggesting.  Using `--with-texmf=/dir' you can
     specify where the TeX TDS directory hierarchy resides, and the TeX
     files will be installed in `/dir/tex/latex/preview'.  If you want
     to specify an exact directory for the preview TeX files, use
     `--with-preview-dir=/dir'. In this case, the files will be placed
     in `/dir'.

`--with-lispdir=/dir'
     This tells where to install Emacs Lisp files.  Normally, this
     option is unnecessary, but may be used if you don't like the
     directory that configure is suggesting.

`--disable-8bit-test'
     There can be problems if your LaTeX implementation is not 8-bit
     clean.  Check `PROBLEMS' file or *Note Known problems::).  This
     switch disables the 8-bit test, in case you know that your
     installation is clean and the test is simply failing.  By
     specifying this switch, you signal your acceptance of having
     preview-latex fail on LaTeX files containing 8-bit characters.

     Failure of this test can also happen if you have fetched
     preview-latex via CVS and have run `autoconf' by hand instead of
     using the provided `autogen.sh': `autoconf' unfortunately clobbers
     the language environment settings, and there is no way portable
     across versions to preserve them.  The current version of the
     `autogen.sh' script tries to work around this deficiency.

Build/install
=============

   Once `configure' has been run, simply enter

     make

at the prompt to byte-compile the lisp files, extract the TeX files and
build the documentation files.  To install the files into the locations
chosen earlier, type

     make install

You may need special privileges to install, e.g., if you are installing
into system directories.

Loading the package
===================

   You need to place a few lines in your personal `.emacs' file (or a
site-wide configuration file).

   If you used the option `--with-lispdir', you have to make sure that
the directory where you installed the lisp files of preview-latex is in
Emacs' `load-path' variable.  This could mean, for example, adding the
line `(add-to-list 'load-path "~/elisp/preview")' to your `.emacs' file.

   Next put the following lines into your `.emacs' file:

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

   This will make Emacs load `preview.el' and let it install itself
into AUC TeX when you first load a LaTeX file (be sure to have AUC TeX
up and working).  `C-c C-c g <RET>' should then give you a graphics
preview.  You can customize the default option set and other settings
of the Emacs package by entering `M-x customize-group <RET> preview
<RET>'.

   There is a sample file `circ.tex' which you can use for testing
around a bit, and which serves as sort of a reference for initial bug
reports.  See the `PROBLEMS' file or *Note Known problems:: for a list
of known problems.

