1 Installing AUCTeX
*******************

Installing AUCTeX should be simple: merely `./configure', `make', and
`make install'. This does not yet activate the package, but merely
makes it available. See *Note Loading the package:: for the activation.
Please read through this document fully before installing anything.
The installation procedure has changed as compared to earlier versions.
In particular, note that there is some additional information for
MS Windows installations in the file `INSTALL.windows'.

1.1 Prerequisites
=================

   * A recent version of Emacs 21, alternatively XEmacs 21.

     Support for Emacs 20 has been dropped in favor of getting more
     important work done.  For XEmacs, you need at least version 1.84
     of the `xemacs-base' package (released on 01/27/2004) or a sumo
     tarball dated 02/02/2004 or newer for compiling AUCTeX because of
     non-trivial changes in `easy-mmode.el': please use the XEmacs
     package system for upgrading if necessary.  The current developers
     don't have the resources for providing backward compatibility to
     earlier versions.

   * A working LaTeX installation

     This is not really needed to _install_ the package, but will be
     required for useful operation of it. The elisp of AUCTeX will
     probably run without LaTeX, but you will find relatively little
     use for it.

   * The `texinfo' package

     This is needed for building the documentation. If you don't have
     this, or you have a too old version of it (try building and you'll
     find out), you may download a separate tar file with the prebuilt
     documentation from Savannah and install it over the main unpacked
     tar archive.

1.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 AUCTeX from CVS rather than a regular
release, you will have to first generate `./configure' by running
`autogen.sh' in the `auctex' 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 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-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.

`--with-packagedir=/DIR'
     This tells where to install the XEmacs Package.  Again, this
     option is normally unnecessary, but may be used if you don't like
     the directory that configure is suggesting, and you know that
     XEmacs regards the directory you specify as a package directory.

     If you are installing AUCTeX for a single user, and you have
     installed no XEmacs packages as that user before, then `configure'
     may try to install AUCTeX in the systemwide package directory
     (that it cannot write to), causing installation to fail.  In that
     case, a good value for this option is `~/.xemacs/xemacs-packages',
     as XEmacs looks there for per-user packages by default.

`--with-tex-input-dirs=/DIR-1/;/DIR-2/;...;/DIR-N/'
     This option allows to specify the directories to be used for file
     searches, e.g. for completion of LaTeX or BibTeX style file names.
     They will be used in the variable `TeX-macro-global'.

     Normally only the subdirectories `tex/' and `bibtex/bst/' below
     the used texmf trees should be relevant.  Putting the roots of
     texmf trees here is possible but may slow down file searching.

     The directories should be separated by semicolons and each has to
     end with a directory separator, i.e. a slash or a backslash
     respectively.

`--with-auto-dir=/DIR'
     You can use this option to specify the directory containing
     automatically generated information.  It is not necessary for most
     TeX installs, but may be used if you don't like the directory that
     configure is suggesting.

`--help'
     This is not an option specific to AUCTeX. 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'.


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

Once `configure' has been run, simply enter

     make
   at the prompt to byte-compile the lisp 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.

1.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 AUCTeX as a package and
activate it.  Restarting XEmacs should then make the package visible,
and `C-c C-c' should give you a command prompt.

   If you used `--with-packagedir', you have to make sure that the
directory `lisp/auctex' under the directory you specified is in XEmacs'
`load-path' variable.

   For GNU Emacs, the recommended way to activate AUCTeX is to add the
following line to your `.emacs' file:

     (require 'tex-site)

   If you used `--with-lispdir', you have to make sure that the
directory specified is in Emacs' `load-path' variable, so that you
would instead use, e.g.,

     (setq load-path (cons "~/elisp" load-path))
     (require 'tex-site)

   For site-wide activation in GNU Emacs, see below.

   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.

1.5 Providing AUCTeX 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. The policy with regard to AUCTeX 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.

   If, however, you are certain that the users all prefer AUCTeX, you
may place the following line in `default.el':

     (require 'tex-site)

   XEmacs uses a package system.  The default AUCTeX installation
should cater for everything necessary in that case.

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

   GNU Emacs users can solve this problem by 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.  That way, it is reasonably easy to maintain a bunch of
additional packages, 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).  This should
only need to be done once, and should be needed fairly rarely; if you
have installed any personal XEmacs packages before, `configure' should
detect that, and automatically install AUCTeX there too; equally, if
you have installed AUCTeX somewhere searched by XEmacs, AUCTeX should
be automatically reinstalled over that copy.

   (`configure' may guess wrong if the site administrator has installed
AUCTeX somewhere else: if so, just use the `--with-packagedir' option
to override `configure''s choice.)

   But there is another problem: 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, you'll want the invocation lines described above.  In
addition, you'll want a line such as

     (add-to-list 'load-path "~myself/share/emacs/site-lisp/preview")

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'.)

1.7 Customizing
===============

Most of the site-specific customization should already have happened
during configuration of AUCTeX.  Any further customization can be done
with customization buffers directly in Emacs.  Just type `M-x
customize-group RET AUCTeX RET' to open the customization group for
AUCTeX or use the menu entries provided in the mode menus.  Editing the
file `tex-site.el' as suggested in former versions of AUCTeX should not
be done anymore because the installation routine will overwrite those
changes.

   You might check some variables with a special significance.  They are
accessible directly by typing `M-x customize-variable RET <variable>
RET'.

 -- User Option: TeX-lisp-directory
     The directory where you installed the AUCTeX lisp files.

   This variable is set automatically during configuration.  If you
don't issue a `make install', for example if you don't want to install
AUCTeX in a different place, you will have to set this variable
manually to the location of the compiled files.  It is generally
advisable to do a full installation including `make install' because
program and documentation files will be copied to their proper places.

 -- User Option: TeX-macro-global
     Directories containing the site's TeX style files.

   Normally, AUCTeX will only allow you to complete macros and
environments which are built-in, specified in AUCTeX style files or
defined by yourself.  If you issue the `M-x TeX-auto-generate-global'
command after loading AUCTeX, you will be able to complete on all
macros available in the standard style files used by your document.  To
do this, you must set this variable to a list of directories where the
standard style files are located.  The directories will be searched
recursively, so there is no reason to list subdirectories explicitly.
Automatic configuration will already have set the variable for you if
it could use the program `kpsewhich'.  In this case you normally don't
have to alter anything.

1.8 Contributed files
=====================

There are several files that are not part of AUCTeX proper, but
included in the distribution in case they are useful.

`bib-cite.el'
     Better support for bibliographies and much more.

`tex-jp.el'
     Support for Japanese.


   They can be installed together with AUCTeX by executing `make
contrib' and `make install-contrib'.  Read the comments in the start of
each file for more information about how to use the files, what they
do, and who wrote and maintains them.

