Installing AUCTeX
*****************

The modern and strongly recommended way of installing AUCTeX is by using
the Emacs package manager integrated in Emacs 24 and greater (ELPA).
Simply do ‘M-x list-packages <RET>’, mark the auctex package for
installation with ‘i’, and hit ‘x’ to execute the installation
procedure.  That’s all.

   ‘use-package’ users can use this simple recipe in their
‘user-init-file’ which essentially does the same as the manual
installation explained above.

     (use-package tex
       :ensure auctex)

   Using the ELPA version has several advantages.  Besides being
platform and OS independent, you will receive intermediate bugfix
releases between major AUCTeX releases conveniently.  For past ELPA
releases, see <https://elpa.gnu.org/packages/auctex.html>.

   The remainder of this section is about installing AUCTeX from a
release tarball or from a checkout of the AUCTeX repository.

   Installing AUCTeX 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).

   On many systems, this will already activate the package, making its
modes the default instead of the built-in modes of Emacs.  If this is
not the case, consult *note Loading the package::.  Please read through
this document fully before installing anything.  The installation
procedure has changed as compared to earlier versions.  Users of
MS Windows are asked to consult the file ‘INSTALL.windows’.

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

   • GNU Emacs 25.1 or higher

     Using preview-latex requires a version of Emacs compiled with image
     support.

     Windows
          Precompiled versions are available from
          <https://ftp.gnu.org/gnu/emacs/windows/>.
     macOS
          For an overview of precompiled versions of Emacs for macOS see
          for example <https://www.emacswiki.org/emacs/EmacsForMacOS>.
     GNU/Linux
          Most GNU/Linux distributions nowadays provide a recent variant
          of Emacs via their package repositories.
     Self-compiled
          Compiling Emacs yourself requires a C compiler and a number of
          tools and development libraries.  Details are beyond the scope
          of this manual.  Instructions for checking out the source code
          can be found at <https://savannah.gnu.org/git/?group=emacs>.

   • A working TeX installation

     Well, AUCTeX would be pointless without that.  Processing
     documentation requires TeX, LaTeX and Texinfo during installation.
     preview-latex requires Dvips or ‘dvipng’ for its operation in DVI
     mode.  The default configuration of AUCTeX is tailored for
     TeX Live-based distributions, but can be adapted easily.

   • A recent Ghostscript

     This is needed for operation of preview-latex in both DVI and PDF
     mode.  Ghostscript version 7.07 or newer is required.

   • GNU make

     Recent AUCTeX uses GNU make specific capabilities in the Makefiles.
     If your OS’s default ‘make’ command is not GNU make, you have to
     obtain it in order to build AUCTeX by yourself.  GNU make is
     sometimes provided under the name ‘gmake’ in your OS’s binary
     package system.

   • The Texinfo package

     Strictly speaking, you can get away without it if you are building
     from the distribution tarball, have not modified any files and
     don’t need a printed version of the manual: the pregenerated info
     file is included in the tarball.  At least version 4.0 is required.

   For some known issues with various software, see the
‘PROBLEMS.preview’ 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 AUCTeX from Git rather than a regular
release, you will have to first follow the instructions in
‘README.GIT’).

   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=PREFIX’
     All automatic placements for package components will be chosen from
     sensible existing hierarchies below this: directories like ‘man’,
     ‘share’ and ‘bin’ are supposed to be directly below PREFIX.

     Only if no workable placement can be found there, in some cases an
     alternative search will be made in a prefix deduced from a suitable
     binary.

     ‘/usr/local’ is the default PREFIX, intended to be suitable for a
     site-wide installation.  If you are packaging this as an operating
     system component for distribution, the setting ‘/usr’ will probably
     be the right choice.  See *note Advice for package providers:: for
     detail.

     If you are planning to install the package as a single
     non-priviledged user, you will typically set PREFIX to your home
     directory.  Consult *note Advice for non-privileged users:: for
     addtional instructions.

‘--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-lispdir=LISPDIR’
     This option specifies the location of the ‘site-lisp’ directory
     within ‘load-path’ under which the files will get installed (the
     bulk will get installed in a subdirectory).  ‘./configure’ should
     figure this out by itself.

‘--with-auctexstartfile=auctex.el’
‘--with-previewstartfile=preview-latex.el’
     This is the name of the respective startup files.  If LISPDIR
     contains a subdirectory ‘site-start.d’, the start files are placed
     there, and ‘site-start.el’ should load them automatically.  Please
     be aware that you must not move the start files after installation
     since other files are found _relative_ to them.

‘--with-packagelispdir=auctex’
     This is the directory where the bulk of the package gets located.
     The startfile adds this into ‘load-path’.

‘--with-auto-dir=/DIR’
     You can use this option to specify the directory containing
     automatically generated information by ‘M-x
     TeX-auto-generate-global <RET>’.  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’.

‘--disable-preview’
     This disables configuration and installation of preview-latex.
     This option is not actually recommended.  If your Emacs does not
     support images, you should really upgrade to a newer version.
     Distributors should, if possible, refrain from distributing AUCTeX
     and preview-latex separately in order to avoid confusion and
     upgrade hassles if users install partial packages on their own.

‘--with-texmf-dir=/DIR’
‘--without-texmf-dir’
     This option is used for specifying a TDS-compliant directory
     hierarchy.  Using ‘--with-texmf-dir=/DIR’ you can specify where the
     TeX TDS directory hierarchy resides, and the TeX files will get
     installed in ‘/DIR/tex/latex/preview/’.

     If you use the ‘--without-texmf-dir’ option, the TeX-related files
     will be kept in the Emacs Lisp tree, and at runtime the ‘TEXINPUTS’
     environment variable will be made to point there.  You can install
     those files into your own TeX tree at some later time with ‘M-x
     preview-install-styles <RET>’.

‘--with-tex-dir=/DIR’
     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’, and you’ll also need the following option:

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

3 Build/install and uninstall
*****************************

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.

   Should you want to completely remove the installed package, in the
same directory you built AUCTeX run

     make uninstall

You will need administration privileges if you installed the package
into system directories.

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

You can detect the successful activation of AUCTeX and preview-latex in
the menus after loading a LaTeX file like ‘circ.tex’: AUCTeX then gives
you a ‘Command’ menu, and preview-latex gives you a ‘Preview’ menu.

   With Emacs (or if you explicitly disabled use of the package system),
the startup files ‘auctex.el’ and ‘preview-latex.el’ may already be in a
directory of the ‘site-start.d/’ variety if your Emacs installation
provides it.  In that case they should be automatically loaded on
startup and nothing else needs to be done.  If not, they should at least
have been placed somewhere in your ‘load-path’.  You can then load them
by placing the lines

     (load "auctex.el" nil t t)
     (load "preview-latex.el" nil t t)
into your init file such as ‘init.el’ or ‘.emacs’.

   If you explicitly used ‘--with-lispdir’, you may need to add the
specified directory into Emacs’ ‘load-path’ variable by adding something
like

     (add-to-list 'load-path "~/elisp")
before the above lines into your Emacs startup file.

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

   Once activated, the modes provided by AUCTeX are used per default for
all supported file types.  If you want to change the modes for which it
is operative instead of the default, use
     M-x customize-option <RET> TeX-modes <RET>

   If you want to remove a preinstalled AUCTeX completely before any of
its modes have been used,
     (unload-feature 'tex-site)
should accomplish that.

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.

   There are people that prefer the built-in Emacs modes for editing TeX
files, in particular plain TeX users.  There are various ways to tell
AUCTeX even after auto-activation that it should not get used, and they
are described in the ‘README’ file.

   So if you have users that don’t want to use the preinstalled AUCTeX,
they can easily get rid of it.  Activating AUCTeX by default is
therefore a good choice.

   If the installation procedure did not achieve this already by placing
‘auctex.el’ and ‘preview-latex.el’ into a possibly existing
‘site-start.d’ directory, you can do this by placing

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

in the system-wide ‘site-start.el’.

   The ‘--without-texmf-dir’ option can be convenient for systems that
are intended to support more than a single TeX distribution.  Since more
often than not TeX packages for operating system distributions are
either much more outdated or much less complete than separately provided
systems like TeX Live, this method may be generally preferable when
providing packages.

   The following package structure would be adequate for a typical fully
supported Unix-like installation:

‘preview-tetex’
     Style files and documentation for ‘preview.sty’, placed into a TeX
     tree where it is accessible from the teTeX executables usually
     delivered with a system.  If there are other commonly used TeX
     system packages, it might be appropriate to provide separate
     packages for those.
‘auctex-emacs-tetex’
     This package will require the installation of ‘preview-tetex’ and
     will record in ‘TeX-macro-global’ where to find the TeX tree.  It
     is also a good idea to run
          emacs -batch -f TeX-auto-generate-global
     when either AUCTeX or teTeX get installed or upgraded.  If your
     users might want to work with a different TeX distribution
     (nowadays pretty common), instead consider the following:
‘auctex-emacs’
     This package will be compiled with ‘--without-texmf-dir’ and will
     consequently contain the ‘preview’ style files in its private
     directory.  It will probably not be possible to initialize
     ‘TeX-macro-global’ to a sensible value, so running
     ‘TeX-auto-generate-global’ does not appear useful.  This package
     would neither conflict with nor provide ‘preview-tetex’.

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 pass more
options to the ‘configure’ script.

   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 often need to specify ‘--with-lispdir’ option as well.  If you
haven’t installed Emacs under your home directory and use Emacs
installed in system directories, the ‘configure’ script might not be
able to figure out suitable place to install lisp files under your home
directory.  In that case, the ‘configure’ script would silently choose,
by default, the ‘site-lisp’ directory within ‘load-path’ for the place,
where administration privileges are usually required to put relevant
files.  Thus you will have to tell the ‘configure’ script explicitly
where to put those files by, e.g.,
‘--with-lispdir=‘/home/myself/share/emacs/site-lisp’’.

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

   In addition, you will have to tell ‘configure’ script where to
install TeX-related files such as ‘preview.sty’ if preview-latex isn’t
disabled.  It is enough to specify ‘--with-texmf-dir=$HOME/texmf’ for
most typical cases, but you have to create the direcotry ‘$HOME/texmf’
in advance if it doesn’t exist.  If this prescription doesn’t work,
consider using one or more of the options ‘--with-texmf-dir=/DIR’,
‘--without-texmf-dir’, ‘--with-tex-dir=/DIR’ and ‘--with-doc-dir=/DIR’.
See *note Configure:: for detail of these options.

   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 GNU Emacs, it should be sufficient if people just do

     (load "~myself/share/emacs/site-lisp/auctex.el" nil t t)
     (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
===============================

For making the info files accessible from within Elisp, something like
the following might be convenient to add into your or other people’s
startup files:

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

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

If you want others to be able to share your installation, you should
configure it using ‘--without-texmf-dir’, in which case things should
work as well for them as for you.

6.1 Using AUCTeX from local Git repo
====================================

With the techniques described above, it is also possible to use AUCTeX
directly from a local Git repository.  Let’s assume you have your Git
repositories under ‘~/development/’.

   First, you have to fetch a copy of the AUCTeX Git repository.  In a
shell, change directory to ‘~/development/’ and do:
     git clone https://git.savannah.gnu.org/git/auctex.git

   Now change directory to ‘~/development/auctex’ and run
‘./autogen.sh’.  Next thing is to run ‘configure’ like this:
     ./configure --without-texmf-dir --with-lispdir=.

When finished, simply enter
     make
and you’re finished.  Note that the ‘make install’ step is not
necessary.

   Now you have to tell Emacs about the plan.  The following variables
must be set in your init file because their normal values are only
correct when AUCTeX is installed:
     (setq TeX-data-directory "~/development/auctex"
           TeX-lisp-directory TeX-data-directory)

The info files will be available with this:
     (eval-after-load 'info
        '(add-to-list 'Info-additional-directory-list
                      "~/development/auctex/doc"))

Now you’re ready to load ‘auctex.el’ and ‘preview-latex.el’ out of this
directory:
     (load "~/development/auctex/auctex.el" nil t t)
     (load "~/development/auctex/preview-latex.el" nil t t)

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 options with a special significance.  They are
accessible directly by typing ‘M-x customize-option <RET> <option>
<RET>’.

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

