Installing preview-latex
************************

   Installing preview-latex should be simple: merely `./configure',
`make', and `make install' for a standard site-wide installation (most
other installations can be done by specifying a `--prefix=...' option).
This does not yet activate the package, but merely makes it available.
See *Note Loading the package:: for the activation.  Note that unlike
most emacs add-ins, preview-latex consists of a TeX part and an Emacs
part (that uses AUCTeX).  This makes configuration a bit trickier than
normal.  Please read through this document fully before installing
anything.

1 Prerequisites
***************

   * A recent version of Emacs 21, alternatively XEmacs

     The first version known to work with preview-latex is Emacs 21.1.
     Since preview-latex heavily exercises newer features, getting the
     latest release is a good idea.  Developer versions of Emacs 22 are
     mostly preferable to the released versions of Emacs 21 due to
     performance and handling reasons.  XEmacs (21.4.15 or later, but
     not the withdrawn 21.4.16) is supported nominally, but is not
     particularly recommended because of handling, image quality and
     stability reasons.

     There is additional information for Windows installations in the
     file `INSTALL.windows'.

   * A working AUCTeX installation

     AUCTeX can be found at `http://www.gnu.org/software/auctex'.  This
     site now provides up-to-date tarballs as well as RPMs.  At the time
     of this writing, the latest version is 11.55.  You need at least
     11.51 to support PDFLaTeX operation.

   * 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 versions of GhostScript
     nowadays in use should work fine (version 7.0 and newer).  If you
     encounter problems, check the `PROBLEMS' file.

   * The `texinfo' package

     This is needed for rebuilding the documentation in the CVS version
     or if you touched any source file.  At least version 4.0 is
     required.

   For some known issues with various software, see the `PROBLEMS' file.

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

`--prefix=`/usr/local''
     All automatic placements for package components will be chosen from
     sensible existing hierarchies below this.  `/usr/local' is the
     default setting for site-wide installation.  If you are packaging
     this as an operating system component for distribution, the setting
     `/usr' will probably be the right choice.  If you are planning to
     install the package as a single non-priviledged user, you will
     typically set PREFIX to your home directory.  And if you have
     installed an alternative version of Emacs for testing purposes,
     the prefix (something like `/usr/local/emacs-22') will be the same
     you used when installing Emacs.

`--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 executable, you can
     specify it with this option.

`--with-xemacs[=/PATH/TO/XEMACS]'
     Configure for generation under XEmacs (Emacs is the default).
     Again, the name of the right XEmacs executable can be specified,
     complete with path if necessary.

`--with-packagedir=/DIR'
     This XEmacs-only option configures the directory for XEmacs
     packages.  A typical user-local setting would be
     `~/.xemacs/xemacs-packages'.  If this directory exists and is
     below PREFIX, it should be detected automatically.  This will
     install and activete the package.  Emacs uses a different
     installation scheme:

`--with-lispdir=/DIR'
     This Emacs-only option specifies the location of the startup file
     `preview-latex.el' which should be somewhere in the LOAD-PATH.
     `configure' should figure this out by itself.  However, some Emacs
     installations have a directory commonly called `site-start.d/'
     where files get automatically loaded.  If you want preview-latex
     to be activated automatically, you can specify such a startup
     directory here.  If you do this, you'll also need

`--with-packagelispdir=../PREVIEW'
     This is the directory where the bulk of the package gets located.
     Since `preview-latex.el' already adds this into LOAD-PATH, you
     don't need to place it in the search path.  You might want to
     place an empty file called .NOSEARCH in this directory to speed up
     searches.  If this directory is given with a relative path, it is
     considered _relative_ to the LISPDIR variable.  The proposed
     setting would be typical if you set LISPDIR to some
     `site-lisp/site-start.d/' directory.

`--with-tex-site=/DIR'
     If AUCTeX is installed in a non-standard location, use this option
     to specify the location of its `tex-site.el' file so that it can be
     found during compilation.

`--with-texmf-dir=/DIR
     --with-tex-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=/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-tex-dir=/DIR'. In this case, the files will be placed in
     `/DIR'.

`--with-doc-dir=/DIR'
     This option may be used to specify where the TeX documentation
     goes.  It is to be used when you are using `--with-tex-dir=/DIR',
     but is normally not necessary otherwise.

`--help'
     This is not an option specific to preview-latex. A number of
     standard options to `configure' exist, and we do not have the room
     to describe them here; a short description of each is available,
     using `--help'.


3 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.

4 Loading the package
*********************

First you should make sure that AUCTeX gets loaded.  You then need to
place a few lines in your personal `.emacs' file (or a site-wide
configuration file).

   For XEmacs, if you specified a valid package directory during
installation, or none at all, then XEmacs installation should do
everything necessary in order to install preview-latex as a package and
activate it.  Restarting XEmacs should then make the package visible,
and `C-c C-p C-d' should produce previews.

   If you used `--with-packagedir', you have to make sure that the
directory `lisp/preview' under the directory you specified is in
XEmacs' `load-path' variable.  The package system should normally cater
for that.

   With Emacs (or if you explicitly disabled use of the package system),
the file `preview-latex.el' (which is generated during the
installation) may already be in a directory of the `site-start.d/'
variety if your Emacs installation provides it and you followed the
suggestion in the configuration section above.  In that case it should
be automatically loaded on startup and nothing else needs to be done.
If not, it should at least have been placed somewhere in your
LOAD-PATH.  You can then load it with

     (load "preview-latex.el" nil t t)

   That is all.  There are other ways of achieving the equivalent thing,
but we don't mention them here any more since they are not better, and
people got confused into trying everything at once.

   When you first load a LaTeX file, `preview.el' itself gets loaded
(if you have AUCTeX up and working).  `C-c C-p C-d' 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 for a list of known problems.

5 Providing preview-latex as a package
**************************************

As a package provider, you should make sure that your users will be
served best according to their intentions, and keep in mind that a
system might be used by more than one user, with different preferences.
The use of packages should in general not impact performance negatively
if a user chooses not to employ it, but should be as convenient as
possible. For example, the policy with regard to AUCTeX typically has
been to _refrain_ from activating it automatically when it is installed
as a package.  This is reasonable because

   * Emacs comes with a simpler default TeX mode with different
     keybindings.  Some users might prefer that.

   * AUCTeX is activated via `(require 'tex-site)'.  Once this has
     happened, it is not possible to get back the original TeX mode.  A
     site-wide default would for this reason be hard to override.

   In contrast, preview-latex does not affect operation of AUCTeX
unless you exercise its features.  The recommended invocation (see
above), also provided in the autogenerated file `preview-latex.el',
will delay loading and activating preview-latex until the first LaTeX
file gets loaded.  For this reason, should a user decide that he does
not want to get preview-latex loaded and activated, placing the line

     (remove-hook 'LaTeX-mode-hook 'LaTeX-preview-setup)

in his personal configuration file will be completely sufficient to keep
his personal setup free from any impact of preview-latex's presence.

   For this reason we recommend automatically activating the package.
For Emacs, this is achieved by installing `preview-latex.el' in a
`site-start.d' directory (if provided by your installation) like
mentioned above, or by explicitly loading it from your `site-start.el'
file.  For the XEmacs package system, the default preview-latex
installation will do something equivalent.

   For RPM files we include a `preview-latex.spec' file in the tarball
distribution, suitable for recent RedHat systems, that should do just
that.

6 Installation for non-privileged users
***************************************

Often people without system administration privileges want to install
software for their private use.  In that case you need to specify more
options top the `configure' script.  For XEmacs users, this is fairly
easy, because the XEmacs package system has been designed to make this
sort of thing practical: but GNU Emacs users (and XEmacs users for whom
the package system is for some reason misbehaving) may need to do a
little more work.

   The main expedient is using the `--prefix' option to the `configure'
script, and let it point to the personal home directory.  In that way,
resulting binaries will be installed under the `bin' subdirectory of
your home directory, manual pages under `man' and so on.  It is
reasonably easy to maintain a bunch of personal software, since the
prefix argument is supported by most `configure' scripts.

   You'll have to add something like
`/home/myself/share/emacs/site-lisp' to your `load-path' variable, if
it isn't there already.

   XEmacs users can achieve the same end by pointing `configure' at an
appropriate package directory (normally
`--with-packagedir=~/.xemacs/xemacs-packages' will serve).  The package
directory stands a good chance at being detected automatically as long
as it is in a subtree of the specified PREFIX.

   Now here is another thing to ponder: perhaps you want to make it easy
for other users to share parts of your personal Emacs configuration.  In
general, you can do this by writing `~myself/' anywhere where you
specify paths to something installed in your personal subdirectories,
not merely `~/', since the latter, when used by other users, will point
to non-existent files.

   For yourself, it will do to manipulate environment variables in your
`.profile' resp. `.login' files.  But if people will be copying just
Elisp files, their copies will not work.  While it would in general be
preferable if the added components where available from a shell level,
too (like when you call the standalone info reader, or try using
`preview.sty' for functionality besides of Emacs previews), it will be
a big help already if things work from inside of Emacs.

   Here is how to do the various parts:

Making the Elisp available
==========================

In XEmacs, you should ask the other users to add symbolic links in their
`~/.xemacs/xemacs-packages/lisp', `~/.xemacs/xemacs-packages/info' and
`~/.xemacs/xemacs-packages/etc' directories. (Alas, there is presently
no easy programmatic way to do this, except to have a script do the
symlinking for them.)

   In GNU Emacs, It should be sufficient if people just do

     (load "~myself/share/emacs/site-lisp/preview-latex.el" nil t t)

   where the path points to your personal installation.  The rest of the
package should be found relative from there without further ado.

Making the Info files available
===============================

While for yourself, you'll probably want to manipulate the `INFOPATH'
variable; for access inside of Elisp something like the following might
be convenient:

     (eval-after-load 'info
        '(add-to-list 'Info-directory-list "~myself/info"))

   In XEmacs, as long as XEmacs can see the package, there should be no
need to do anything at all; the info files should be immediately
visible.  However, you might want to set `INFOPATH' anyway, for the
sake of standalone readers outside of XEmacs. (The info files in XEmacs
are normally in `~/.xemacs/xemacs-packages/info'.)

Making the LaTeX style available
================================

Again, for yourself you want to manipulate the `TEXINPUTS' environment
variable or an appropriate setting of a personal `texmf.cnf' file.  It
may well be that your site configuration already caters for a personal
user's `texmf' tree, in which case having specified the appropriate
tree to `./configure' will have set up everything for yourself.  If
that personal tree is not located at the equivalent of
`~myself/share/texmf', it is a good idea to make this so with the help
of a symbolic link, so that the usual `--prefix' invocation to
`./configure' is everything that is needed.

   For others, you want to add something like

     (setenv "TEXINPUTS"
             (concat "~myself/share/texmf/tex/latex/preview:"
                     (getenv "TEXINPUTS")))

     (setenv "TEXDOCS"
             (concat "~myself/share/texmf/doc/latex/styles:"
                     (getenv "TEXDOCS")))

   This just exports the relevant directories for preview-latex; you
might have more to share.  Also, the `TEXDOCS' change is hardly likely
to be effective: most people call `texdoc' from a shell window rather
than from inside of Emacs, and those that are interested in the style
documentation will usually want to have the style itself available
anyhow without having to call LaTeX from within Emacs.

   But at least for people just interested in preview-latex from inside
of Emacs, the augmentation of `TEXINPUTS' will be helpful.  Although it
does not appear like it, under `web2c'-based systems like teTeX, this
invocation will also do the right thing in case `TEXINPUTS' has no
previous value.

