AUCTeX

This manual is for AUCTeX (version 11.85 from 2008-02-10), a sophisticated TeX environment for Emacs.

Copyright © 1992, 1993, 1994, 1995, 2001, 2002, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”

AUCTeX is an integrated environment for editing LaTeX, ConTeXt, docTeX, Texinfo, and TeX files.

Although AUCTeX contains a large number of features, there are no reasons to despair. You can continue to write TeX and LaTeX documents the way you are used to, and only start using the multiple features in small steps. AUCTeX is not monolithic, each feature described in this manual is useful by itself, but together they provide an environment where you will make very few LaTeX errors, and makes it easy to find the errors that may slip through anyway.

It is a good idea to make a printout of AUCTeX's reference card ‘tex-ref.tex’ or one of its typeset versions.

If you want to make AUCTeX aware of style files and multi-file documents right away, insert the following in your ‘.emacs’ file.

(setq TeX-auto-save t)
(setq TeX-parse-self t)
(setq-default TeX-master nil)

Another thing you should enable is RefTeX, a comprehensive solution for managing cross references, bibliographies, indices, document navigation and a few other things. (see (reftex)Installation section `Installation' in The RefTeX manual)

For detailed information about the preview-latex subsystem of AUCTeX, see (preview-latex)Top section `Introduction' in The preview-latex Manual.

There is a mailing list for general discussion about AUCTeX: write a mail with “subscribe” in the subject to auctex-request@gnu.org to join it. Send contributions to auctex@gnu.org.

Bug reports should go to bug-auctex@gnu.org, suggestions for new features, and pleas for help should go to either auctex-devel@gnu.org (the AUCTeX developers), or to auctex@gnu.org if they might have general interest. Please use the command M-x TeX-submit-bug-report RET to report bugs if possible. You can subscribe to a low-volume announcement list by sending “subscribe” in the subject of a mail to info-auctex-request@gnu.org.

 --- The Detailed Node Listing ---

Inserting Frequently Used Commands

Inserting Environment Templates

Advanced Editing Features

Controlling Screen Display

Starting Processors, Viewers and Other Programs

Language Support

Automatic Customization

Writing Your own Style Support

Copying

AUCTeX primarily consists of Lisp files for Emacs (and XEmacs), but there are also installation scripts and files and TeX support files. All of those are free; this means that everyone is free to use them and free to redistribute them on a free basis. The files of AUCTeX are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of the files that constitute AUCTeX, that you receive source code or else can get it if you want it, that you can change these files or use pieces of them in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of parts of AUCTeX, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that there is no warranty for AUCTeX. If any parts are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.

The precise conditions of the licenses for the files currently being distributed as part of AUCTeX are found in the General Public Licenses that accompany them. This manual specifically is covered by the GNU Free Documentation License (see section Copying this Manual).

1. Introduction to AUCTeX

This section of the AUCTeX manual gives a brief overview of what AUCTeX is. It is not an attempt to document AUCTeX. Real documentation for AUCTeX is available in the rest of the manual.

1.1 Installation

Read the section Installing AUCTeX, or Installation under MS Windows, respectively for comprehensive information about how to install AUCTeX.

The installation routine tries to make the modes provided by AUCTeX the default for all supported file types. If this does not happen in your case, add

(load "auctex.el" nil t t)

to your init file and consult the section Loading the package.

If you want to change the modes for which it is operative instead of the default, use

M-x customize-variable 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.

If you are considering upgrading AUCTeX, the recent changes are described in Changes and New Features.

1.2 Features

AUCTeX is a comprehensive customizable integrated environment for writing input files for TeX/LaTeX/ConTeXt/Texinfo using Emacs or XEmacs.

It lets you process your source files by running TeX and related tools (such as output filters, post processors for generating indices and bibliographies, and viewers) from inside Emacs. AUCTeX lets you browse through the errors TeX reported, while it moves the cursor directly to the reported error, and displays some documentation for that particular error. This will even work when the document is spread over several files.

One component of AUCTeX that LaTeX users will find attractive is preview-latex, a combination of folding and in-source previewing that provides true “What You See Is What You Get” experience in your sourcebuffer, while letting you retain full control. preview-latex comes with its own manual, see (preview-latex)Top section `preview-latex' in The preview-latex Manual.

AUCTeX automatically indents your `LaTeX-source', not only as you write it — you can also let it indent and format an entire document. It has a special outline feature, which can greatly help you `getting an overview' of a document.

Apart from these special features, AUCTeX provides a large range of handy Emacs macros, which in several different ways can help you write your documents fast and painlessly.

All features of AUCTeX are documented using the GNU Emacs online documentation system. That is, documentation for any command is just a key click away!

AUCTeX is written entirely in Emacs-Lisp, and hence you can easily add new features for your own needs. It has become recently a GNU project. AUCTeX is distributed under the `GNU General Public License Version 2'.

1.3 Availability

The most recent version is always available at

http://ftp.gnu.org/pub/gnu/auctex/

WWW users may want to check out the AUCTeX page at

http://www.gnu.org/software/auctex/

1.4 Contacts

Various mailing lists exist.

Send a mail with the subject “subscribe” to auctex-request@gnu.org in order to join the general discussion list for AUCTeX. Articles should be sent to auctex@gnu.org. In a similar way, you can subscribe to the info-auctex@gnu.org list for just getting important announcements about AUCTeX. The list bug-auctex@gnu.org is for bug reports which you should usually file with the M-x TeX-submit-bug-report RET command.

If you want to address the developers of AUCTeX themselves with technical issues, they can be found on the discussion list auctex-devel@gnu.org.

2. Installing AUCTeX

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 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 See section Installation under MS Windows.

2.1 Prerequisites

• A recent version of Emacs, alternatively XEmacs

  Emacs 20 is no longer supported, and neither is XEmacs with a version of xemacs-base older than 1.84 (released in sumo from 02/02/2004). Using preview-latex requires a version of Emacs compiled with image support. While the X11 version of Emacs 21 will likely work, Emacs 22 is the preferred platform.

  Windows

  Precompiled versions are available from ftp://ftp.gnu.org/gnu/emacs/windows/.

  Mac OS X

  A precompiled version including an installer as well as preinstalled versions of AUCTeX and preview-latex is available from http://homepage.mac.com/zenitani/emacs-e.html.

  Debian GNU/Linux

  Debian provides ‘emacs22-gtk’ (probably preferable) and ‘emacs22’ packages in its ‘unstable’ distribution.

  Fedora GNU/Linux

  Fedora 8 comes with Emacs 22.1 and Fedora 7 comes with a developer version of the same.

  openSUSE

  openSUSE 10.3 comes with Emacs 22.1. For some earlier openSUSE versions, Emacs 22.1 is available from http://packages.opensuse-community.org/.

  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 http://savannah.gnu.org/cvs/?group=emacs.

  If you really need to use Emacs 21 on platforms where this implies missing image support, you should disable the installation of preview-latex (see below).

  While XEmacs (version 21.4.15, 21.4.17 or later) is supported, doing this in a satisfactory manner has proven to be difficult. This is mostly due to technical shortcomings and differing API's which are hard to come by. If AUCTeX is your main application for XEmacs, you are likely to get better results and support by switching to Emacs. Of course, you can improve support for your favorite editor by giving feedback in case you encounter bugs.

• A working TeX installation

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

• A recent Ghostscript

  This is needed for operation of preview-latex in both DVI and PDF mode. Most versions of Ghostscript nowadays in use should work fine (version 7.0 and newer). If you encounter problems, check (preview-latex)Problems with Ghostscript section `Problems with Ghostscript' in the preview-latex manual.

• 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 (preview-latex)Known problems section `Known problems' in the preview-latex manual.

2.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 follow the instructions in ‘README.CVS’).

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: 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. If you are planning to install the package as a single non-priviledged user, you will typically set prefix to your home directory.

--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 activate the package.

--without-packagedir

This XEmacs-only option switches the detection of a package directory and corresponding installation off. Consequently, the Emacs installation scheme will be used. This might be appropriate if you are using a different package system/installer than the XEmacs one and want to avoid conflicts.

The Emacs installation scheme has the following options:

--with-lispdir=/dir

This Emacs-only 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. 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. If you use ‘--help=recursive’, then also preview-latex-specific options will get listed.

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

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

2.4 Loading the package

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

For XEmacs, if the installation occured into a valid package directory (which is the default), then this should work out of the box.

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 ‘~/.emacs’ file.

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 See section Providing AUCTeX as a package.

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.

2.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 Introduction to AUCTeX.

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

If your package is intended as an XEmacs package or to accompany a precompiled version of Emacs, you might not know which TeX system will be available when preview-latex gets used. In this case you should build using the --without-texmf-dir option described previously. This can also 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’.

‘auctex-xemacs-tetex’

‘auctex-xemacs’

Those are the obvious XEmacs equivalents. For XEmacs, there is the additional problem that the XEmacs sumo package tree already possibly provides its own version of AUCTeX, and the user might even have used the XEmacs package manager to updating this package, or even installing a private AUCTeX version. So you should make sure that such a package will not conflict with existing XEmacs packages and will be at an appropriate place in the load order (after site-wide and user-specific locations, but before a distribution-specific sumo package tree). Using the --without-packagedir option might be one idea to avoid conflicts. Another might be to refrain from providing an XEmacs package and just rely on the user or system administrator to instead use the XEmacs package system.

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

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

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"))

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

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.

2.7 Installation under MS Windows

In a Nutshell

The following are brief installation instructions for the impatient. In case you don't understand some of this, run into trouble of some sort, or need more elaborate information, refer to the detailed instructions further below.

1. Install the prerequisites, i.e. Emacs or XEmacs, MSYS or Cygwin, a TeX system, and Ghostscript.
2. Open the MSYS shell or a Cygwin shell and change to the directory containing the unzipped file contents.
3. Configure AUCTeX:

   For Emacs: Many people like to install AUCTeX into the pseudo file system hierarchy set up by the Emacs installation. Assuming Emacs is installed in ‘C:/Program Files/Emacs’ and the directory for local additions of your TeX system, e.g. MiKTeX, is ‘C:/localtexmf’, you can do this by typing the following statement at the shell prompt:

   ./configure --prefix='C:/Program Files/Emacs' \ --infodir='C:/Program Files/Emacs/info' \ --with-texmf-dir='C:/localtexmf'

   For XEmacs: You can install AUCTeX as an XEmacs package. Assuming XEmacs is installed in ‘C:/Program Files/XEmacs’ and the directory for local additions of your TeX system, e.g. MiKTeX, is ‘C:/localtexmf’, you can do this by typing the following command at the shell prompt:

   ./configure --with-xemacs='C:/Program Files/XEmacs/bin/xemacs' \ --with-texmf-dir='C:/localtexmf'

   The commands above are examples for common usage. More on configuration options can be found in the detailed installation instructions below.

   If the configuration script failed to find all required programs, make sure that these programs are in your system path and add directories containing the programs to the PATH environment variable if necessary. Here is how to do that in W2000/XP:

   2. On the desktop, right click “My Computer” and select properties.
   3. Click on “Advanced” in the “System Properties” window.
   4. Select “Environment Variables”.
   5. Select “path” in “System Variables” and click “edit”. Move to the front in the line (this might require scrolling) and add the missing path including drive letter, ended with a semicolon.
4. If there were no further error messages, type

   make

   In case there were, please refer to the detailed description below.

5. Finish the installation by typing

   make install

Detailed Installation Instructions

Installation of AUCTeX under Windows is in itself not more complicated than on other platforms. However, meeting the prerequisites might require more work than on some other platforms, and feel less natural.

If you are experiencing any problems, even if you think they are of your own making, be sure to report them to auctex-devel@gnu.org so that we can explain things better in future.

Windows is a problematic platform for installation scripts. The main problem is that the installation procedure requires consistent file names in order to find its way in the directory hierarchy, and Windows path names are a mess.

The installation procedure tries finding stuff in system search paths and in Emacs paths. For that to succeed, you have to use the same syntax and spelling and case of paths everywhere: in your system search paths, in Emacs' load-path variable, as argument to the scripts. If your path names contain spaces or other `shell-unfriendly' characters, most notably backslashes for directory separators, place the whole path in ‘"double quote marks"’ whenever you specify it on a command line.

Avoid `helpful' magic file names like ‘/cygdrive/c’ and ‘C:\PROGRA~1\’ like the plague. It is quite unlikely that the scripts will be able to identify the actual file names involved. Use the full paths, making use of normal Windows drive letters like ‘ 'C:/Program Files/Emacs' ’ where required, and using the same combination of upper- and lowercase letters as in the actual files. File names containing shell-special characters like spaces or backslashes (if you prefer that syntax) need to get properly quoted to the shell: the above example used single quotes for that.

Ok, now here are the steps to perform:

1. You need to unpack the AUCTeX distribution (which you seemingly have done since you are reading this). It must be unpacked in a separate installation directory outside of your Emacs file hierarchy: the installation will later copy all necessary files to their final destination, and you can ultimately remove the directory where you unpacked the files.

   Line endings are a problem under Windows. The distribution contains only text files, and theoretically most of the involved tools should get along with that. However, the files are processed by various utilities, and it is conceivable that not all of them will use the same line ending conventions. If you encounter problems, it might help if you try unpacking (or checking out) the files in binary mode, if your tools allow that.

   If you don't have a suitable unpacking tool, skip to the next step: this should provide you with a working ‘unzip’ command.

2. The installation of AUCTeX will require the MSYS tool set from http://www.mingw.org/ or the Cygwin tool set from http://cygwin.com/. The latter is slower and larger (the download size of the base system is about 15 MB) but comes with a package manager that allows for updating the tool set and installing additional packages like, for example, the spell checker aspell.

   If Cygwin specific paths like ‘/cygdrive/c’ crop up in the course of the installation, using a non-Cygwin Emacs could conceivably cause trouble. Using Cygwin either for everything or nothing might save headaches, if things don't work out.

3. Install a current version of XEmacs from http://www.xemacs.org/ or Emacs 22 from ftp://ftp.gnu.org/gnu/emacs/windows/. Emacs 22 is the recommended choice because it is currently the primary platform for AUCTeX development.
4. You need a working TeX installation. One popular installation under Windows is MiKTeX. Another much more extensive system is TeX Live which is rather close to its Unix cousins.
5. A working copy of Ghostscript is required for preview-latex operation. Examining the output from

   gswin32c -h

   on a Windows command line should tell you whether your Ghostscript supports the png16m device needed for PNG support. MiKTeX apparently comes with its own Ghostscript called ‘mgs.exe’.

6. Perl is needed for rebuilding the documentation if you are working with a copy from CVS or have touched documentation source files in the preview-latex part. If the line endings of the file ‘preview/latex/preview.dtx’ don't correspond with what Perl calls \n when reading text files, you'll run into trouble.
7. Now the fun stuff starts. If you have not yet done so, unpack the AUCTeX distribution into a separate directory after rereading the instructions for unpacking above.
8. Ready for takeoff. Start some shell (typically bash) capable of running configure, change into the installation directory and call ./configure with appropriate options.

   Typical options you'll want to specify will be

   --prefix=drive:/path/to/emacs-hierarchy

   which tells ‘configure’ where to perform the installation. It may also make ‘configure’ find Emacs or XEmacs automatically; if this doesn't happen, try one of ‘--with-emacs’ or ‘--with-xemacs’ as described below. All automatic detection of files and directories restricts itself to directories below the prefix or in the same hierarchy as the program accessing the files. Usually, directories like ‘man’, ‘share’ and ‘bin’ will be situated right under prefix.

   This option also affects the defaults for placing the Texinfo documentation files (see also ‘--infodir’ below) and automatically generated style hooks.

   If you have a central directory hierarchy (not untypical with Cygwin) for such stuff, you might want to specify its root here. You stand a good chance that this will be the only option you need to supply, as long as your TeX-related executables are in your system path, which they better be for AUCTeX's operation, anyway.

   --with-emacs

   if you are installing for a version of Emacs. You can use ‘--with-emacs=drive:/path/to/emacs’ to specify the name of the installed Emacs executable, complete with its path if necessary (if Emacs is not within a directory specified in your PATH environment setting).

   --with-xemacs

   if you are installing for a version of XEmacs. Again, you can use ‘--with-xemacs=drive:/path/to/xemacs’ to specify the name of the installed XEmacs executable complete with its path if necessary. It may also be necessary to specify this option if a copy of Emacs is found in your PATH environment setting, but you still would like to install a copy of AUCTeX for XEmacs.

   --with-packagedir=drive:/dir

   is an XEmacs-only option giving the location of the package directory. This will install and activate the package. Emacs uses a different installation scheme:

   --with-lispdir=drive:/path/to/site-lisp

   This Emacs-only option tells a place in load-path below which the files are situated. The startup files ‘auctex.el’ and ‘preview-latex.el’ will get installed here unless a subdirectory ‘site-start.d’ exists which will then be used instead. The other files from AUCTeX will be installed in a subdirectory called ‘auctex’.

   If you think that you need a different setup, please refer to the full installation instructions in Configure.

   --infodir=drive:/path/to/info/directory

   If you are installing into an Emacs directory, info files have to be put into the ‘info’ folder below that directory. The configuration script will usually try to install into the folder ‘share/info’, so you have to override this by specifying something like ‘--infodir='C:/Program Files/info'’ for the configure call.

   --with-auto-dir=drive:/dir

   Directory containing automatically generated information. You should not normally need to set this, as ‘--prefix’ should take care of this.

   --disable-preview

   Use this option if your Emacs version is unable to support image display. This will be the case if you are using a native variant of Emacs 21.

   --with-texmf-dir=drive:/dir

   This will specify the directory where your TeX installation sits. If your TeX installation does not conform to the TDS (TeX directory standard), you may need to specify more options to get everything in place.

   For more information about any of the above and additional options, see Configure.

   Calling ‘./configure --help=recursive’ will tell about other options, but those are almost never required.

   Some executables might not be found in your path. That is not a good idea, but you can get around by specifying environment variables to ‘configure’:

   GS="drive:/path/to/gswin32c.exe" ./configure …

   should work for this purpose. ‘gswin32c.exe’ is the usual name for the required command line executable under Windows; in contrast, ‘gswin32.exe’ is likely to fail.

   As an alternative to specifying variables for the ‘configure’ call you can add directories containing the required executables to the PATH variable of your Windows system. This is especially a good idea if Emacs has trouble finding the respective programs later during normal operation.

9. Run make in the installation directory.
10. Run make install in the installation directory.
11. With XEmacs, AUCTeX and preview-latex should now be active by default. With Emacs, activation depends on a working ‘site-start.d’ directory or similar setup, since then the startup files ‘auctex.el’ and ‘preview-latex.el’ will have been placed there. If this has not been done, you should be able to load the startup files manually with

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

    in either a site-wide ‘site-start.el’ or your personal startup file (usually accessible as ‘~/.emacs’ from within Emacs and ‘~/.xemacs/init.el’ from within XEmacs).

    The default configuration of AUCTeX is probably not the best fit for Windows systems. You might want to add

    (require 'tex-mik)

    or

    (require 'tex-fptex)

    in order to get more appropriate values for MiKTeX and fpTeX, respectively after loading ‘auctex.el’ and ‘preview-latex.el’.

    You can always use

    M-x customize-group RET AUCTeX RET

    in order to customize more stuff, or use the ‘Customize’ menu.

12. Load ‘preview/circ.tex’ into Emacs or XEmacs and see if you get the ‘Command’ menu. Try using it to LaTeX the file.
13. Check whether the ‘Preview’ menu is available in this file. Use it to generate previews for the document.

    If this barfs and tells you that image type ‘png’ is not supported, try adding the line

    (setq preview-image-type 'pnm)

    at the end of your installed version of ‘preview-latex.el’. If this helps, complain to wherever you got your Emacs from: all current Emacs/XEmacs versions capable of running preview-latex by now can be compiled to support PNG images. Which is important, because PNM files take away vast amounts of disk space, and thus also of load/save time.

Well, that about is all. Have fun!

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

3. Quick Start

AUCTeX is a powerful program offering many features and configuration options. If you are new to AUCTeX this might be deterrent. Fortunately you do not have to learn everything at once. This Quick Start Guide will give you the knowledge of the most important commands and enable you to prepare your first LaTeX document with AUCTeX after only a few minutes of reading.

In this introduction, we assume that AUCTeX is already installed on your system. If this is not the case, you should read the file ‘INSTALL’ in the base directory of the unpacked distribution tarball. These installation instructions are available in this manual as well, Installing AUCTeX. We also assume that you are familiar with the way keystrokes are written in Emacs manuals. If not, have a look at the Emacs Tutorial in the Help menu.

If AUCTeX is installed, you might still need to activate it, by inserting

(load "auctex.el" nil t t)

in your user init file.(1) In order to get support for many of the LaTeX packages you will use in your documents, you should enable document parsing as well, which can be achieved by putting

(setq TeX-auto-save t)
(setq TeX-parse-self t)

into your init file. Finally, if you often use \include or \input, you should make AUCTeX aware of the multi-file document structure. You can do this by inserting

(setq-default TeX-master nil)

into your init file. Each time you open a new file, AUCTeX will then ask you for a master file.

3.1 Functions for editing TeX files

3.1.1 Making your TeX code more readable

AUCTeX can do syntax highlighting of your source code, that means commands will get special colors or fonts. You can enable it locally by typing M-x font-lock-mode RET. If you want to have font locking activated generally, enable global-font-lock-mode, e.g. with M-x customize-variable RET global-font-lock-mode RET.

AUCTeX will indent new lines to indicate their syntactical relationship to the surrounding text. For example, the text of a \footnote or text inside of an environment will be indented relative to the text around it. If the indenting has gotten wrong after adding or deleting some characters, use <TAB> to reindent the line, M-q for the whole paragraph, or M-x LaTeX-fill-buffer RET for the whole buffer.

3.1.2 Entering sectioning commands

Insertion of sectioning macros, that is ‘\chapter’, ‘\section’, ‘\subsection’, etc. and accompanying ‘\label’ commands may be eased by using C-c C-s. You will be asked for the section level. As nearly everywhere in AUCTeX, you can use the <TAB> or <SPC> key to get a list of available level names, and to auto-complete what you started typing. Next, you will be asked for the printed title of the section, and last you will be asked for a label to be associated with the section.

3.1.3 Inserting environments

Similarly, you can insert environments, that is ‘\begin{}’–‘\end{}’ pairs: Type C-c C-e, and select an environment type. Again, you can use <TAB> or <SPC> to get a list, and to complete what you type. Actually, the list will not only provide standard LaTeX environments, but also take your ‘\documentclass’ and ‘\usepackage’ commands into account if you have parsing enabled by setting TeX-parse-self to t. If you use a couple of environments frequently, you can use the up and down arrow keys (or M-p and M-n) in the minibuffer to get back to the previously inserted commands.

Some environments need additional arguments. Often, AUCTeX knows about this and asks you to enter a value.

3.1.4 Inserting macros

C-c C-m, or simply C-c RET will give you a prompt that asks you for a LaTeX macro. You can use <TAB> for completion, or the up/down arrow keys (or M-p and M-n) to browse the command history. In many cases, AUCTeX knows which arguments a macro needs and will ask you for that. It even can differentiate between mandatory and optional arguments—for details, see Completion.

An additional help for inserting macros is provided by the possibility to complete macros right in the buffer. With point at the end of a partially written macro, you can complete it by typing M-TAB.

3.1.5 Changing the font

AUCTeX provides convenient keyboard shortcuts for inserting macros which specify the font to be used for typesetting certain parts of the text. They start with C-c C-f, and the last C- combination tells AUCTeX which font you want:

C-c C-f C-b

Insert bold face ‘\textbf{∗}’ text.

C-c C-f C-i

Insert italics ‘\textit{∗}’ text.

C-c C-f C-e

Insert emphasized ‘\emph{∗}’ text.

C-c C-f C-s

Insert slanted ‘\textsl{∗}’ text.

C-c C-f C-r

Insert roman \textrm{∗} text.

C-c C-f C-f

Insert sans serif ‘\textsf{∗}’ text.

C-c C-f C-t

Insert typewriter ‘\texttt{∗}’ text.

C-c C-f C-c

Insert SMALL CAPS ‘\textsc{∗}’ text.

C-c C-f C-d

Delete the innermost font specification containing point.

If you want to change font attributes of existing text, mark it as a region, and then invoke the commands. If no region is selected, the command will be inserted with empty braces, and you can start typing the changed text.

Most of those commands will also work in math mode, but then macros like \mathbf will be inserted.

3.1.6 Other useful features

AUCTeX also tries to help you when inserting the right “quote” signs for your language, dollar signs to typeset math, or pairs of braces. It offers shortcuts for commenting out text (C-c ; for the current region or C-c % for the paragraph you are in). The same keystrokes will remove the % signs, if the region or paragraph is commented out yet. With TeX-fold-mode, you can hide certain parts (like footnotes, references etc.) that you do not edit currently. Support for Emacs' outline mode is provided as well. And there's more, but this is beyond the scope of this Quick Start Guide.

3.2 Creating and viewing output, debugging

3.2.1 One Command for LaTeX, helpers, viewers, and printing

If you have typed some text and want to run LaTeX (or TeX, or other programs—see below) on it, type C-c C-c. If applicable, you will be asked whether you want to save changes, and which program you want to invoke. In many cases, the choice that AUCTeX suggests will be just what you want: first latex, then a viewer. If a latex run produces or changes input files for makeindex, the next suggestion will be to run that program, and AUCTeX knows that you need to run latex again afterwards—the same holds for BibTeX.

When no processor invocation is necessary anymore, AUCTeX will suggest to run a viewer, or you can chose to create a PostScript file using dvips, or to directly print it.

At this place, a warning needs to be given: First, although AUCTeX is really good in detecting the standard situations when an additional latex run is necessary, it cannot detect it always. Second, the creation of PostScript files or direct printing currently only works when your output file is a DVI file, not a PDF file.

Ah, you didn't know you can do both? That brings us to the next topic.

3.2.2 Choosing an output format

From a LaTeX file, you can produce DVI output, or a PDF file directly via pdflatex. You can switch on source specials for easier navigation in the output file, or tell latex to stop after an error (usually \noninteractive is used, to allow you to detect all errors in a single run).

These options are controlled by toggles, the keystrokes should be easy to memorize:

C-c C-t C-p

This command toggles between DVI and PDF output

C-c C-t C-i

toggles interactive mode

C-c C-t C-s

toggles source specials support

C-c C-t C-o

toggles usage of Omega/lambda.

3.2.3 Debugging LaTeX

When AUCTeX runs a program, it creates an output buffer in which it displays the output of the command. If there is a syntactical error in your file, latex will not complete successfully. AUCTeX will tell you that, and you can get to the place where the first error occured by pressing C-c ` (the last character is a backtick). The view will be split in two windows, the output will be displayed in the lower buffer, and both buffers will be centered around the place where the error ocurred. You can then try to fix it in the document buffer, and use the same keystrokes to get to the next error. This procedure may be repeated until all errors have been dealt with. By pressing C-c C-w (TeX-toggle-debug-boxes) you can toggle whether AUCTeX should notify you of overfull and underfull boxes in addition to regular errors.

If a command got stuck in a seemingly infinite loop, or you want to stop execution for other reasons, you can use C-c C-k (for “kill”). Similar to C-l, which centers the buffer you are in around your current position, C-c C-l centers the output buffer so that the last lines added at the bottom become visible.

3.2.4 Running LaTeX on parts of your document

If you want to check how some part of your text looks like, and do not want to wait until the whole document has been typeset, then mark it as a region and use C-c C-r. It behaves just like C-c C-c, but it only uses the document preamble and the region you marked.

If you are using \include or \input to structure your document, try C-c C-b while you are editing one of the included files. It will run latex only on the current buffer, using the preamble from the master file.

4. Inserting Frequently Used Commands

The most commonly used commands/macros of AUCTeX are those which simply insert templates for often used TeX and/or LaTeX/ConTeXt constructs, like font changes, handling of environments, etc. These features are very simple, and easy to learn, and help you avoid stupid mistakes like mismatched braces, or ‘\begin{}’-‘\end{}’ pairs.

4.1 Insertion of Quotes, Dollars, and Braces

Quotation Marks

In TeX, literal double quotes ‘"like this"’ are seldom used, instead two single quotes are used ‘``like this''’. To help you insert these efficiently, AUCTeX allows you to continue to press " to insert two single quotes. To get a literal double quote, press " twice.

Command: TeX-insert-quote count

(") Insert the appropriate quote marks for TeX.

Inserts the value of TeX-open-quote (normally ‘``’) or TeX-close-quote (normally ‘''’) depending on the context. With prefix argument, always inserts ‘"’ characters.

User Option: TeX-open-quote

String inserted by typing " to open a quotation. (See section Using AUCTeX with European Languages, for language-specific quotation mark insertion.)

User Option: TeX-close-quote

String inserted by typing " to close a quotation. (See section Using AUCTeX with European Languages, for language-specific quotation mark insertion.)

User Option: TeX-quote-after-quote

Determines the behavior of ". If it is non-nil, typing " will insert a literal double quote. The respective values of TeX-open-quote and TeX-close-quote will be inserted after typing " once again.

The ‘babel’ package provides special support for the requirements of typesetting quotation marks in many different languages. If you use this package, either directly or by loading a language-specific style file, you should also use the special commands for quote insertion instead of the standard quotes shown above. AUCTeX is able to recognize several of these languages and will change quote insertion accordingly. See section Using AUCTeX with European Languages, for details about this feature and how to control it.

In case you are using the ‘csquotes’ package, you should customize LaTeX-csquotes-open-quote, LaTeX-csquotes-close-quote and LaTeX-csquotes-quote-after-quote. The quotation characters will only be used if both variables—LaTeX-csquotes-open-quote and LaTeX-csquotes-close-quote—are non-empty strings. But then the ‘csquotes’-related values will take precedence over the language-specific ones.

Dollar Signs

In AUCTeX, dollar signs should match like they do in TeX. This has been partially implemented, we assume dollar signs always match within a paragraph. The first ‘$’ you insert in a paragraph will do nothing special. The second ‘$’ will match the first. This will be indicated by moving the cursor temporarily over the first dollar sign.

Command: TeX-insert-dollar arg

($) Insert dollar sign.

Show matching dollar sign if this dollar sign end the TeX math mode. Ensure double dollar signs match up correctly by inserting extra dollar signs when needed if TeX-math-close-double-dollar is non-nil.

With optional arg, insert that many dollar signs.

User Option: TeX-math-close-double-dollar

Control the insertion of double dollar signs for delimiting display math. (Note that you should not use double dollar signs in LaTeX because this practice can lead to wrong spacing in typeset documents.) If the variable is non-nil and you enter a dollar sign that matches a double dollar sign ‘$$’ AUCTeX will automatically insert two dollar signs.

Braces

To avoid unbalanced braces, it is useful to insert them pairwise. You can do this by typing C-c {.

Command: TeX-insert-braces

(C-c {) Make a pair of braces and position the cursor to type inside of them. If there is an active region, put braces around it and leave point after the closing brace.

4.2 Inserting Font Specifiers

Perhaps the most used keyboard commands of AUCTeX are the short-cuts available for easy insertion of font changing macros.

If you give an argument (that is, type C-u) to the font command, the innermost font will be replaced, i.e. the font in the TeX group around point will be changed. The following table shows the available commands, with ∗ indicating the position where the text will be inserted.

C-c C-f C-b

Insert bold face ‘\textbf{∗}’ text.

C-c C-f C-i

Insert italics ‘\textit{∗}’ text.

C-c C-f C-e

Insert emphasized ‘\emph{∗}’ text.

C-c C-f C-s

Insert slanted ‘\textsl{∗}’ text.

C-c C-f C-r

Insert roman \textrm{∗} text.

C-c C-f C-f

Insert sans serif ‘\textsf{∗}’ text.

C-c C-f C-t

Insert typewriter ‘\texttt{∗}’ text.

C-c C-f C-c

Insert SMALL CAPS ‘\textsc{∗}’ text.

C-c C-f C-d

Delete the innermost font specification containing point.

Command: TeX-font arg

(C-c C-f) Insert template for font change command.

If replace is not nil, replace current font. what determines the font to use, as specified by TeX-font-list.

User Option: TeX-font-list

List of fonts used by TeX-font.

Each entry is a list with three elements. The first element is the key to activate the font. The second element is the string to insert before point, and the third element is the string to insert after point. An optional fourth element means always replace if not nil.

4.3 Inserting chapters, sections, etc.

Insertion of sectioning macros, that is ‘\chapter’, ‘\section’, ‘\subsection’, etc. and accompanying ‘\label’'s may be eased by using C-c C-s. This command is highly customizable, the following describes the default behavior.

When invoking you will be asked for a section macro to insert. An appropriate default is automatically selected by AUCTeX, that is either: at the top of the document; the top level sectioning for that document style, and any other place: The same as the last occurring sectioning command.

Next, you will be asked for the actual name of that section, and last you will be asked for a label to be associated with that section. The label will be prefixed by the value specified in LaTeX-section-hook.

Command: LaTeX-section arg

(C-c C-s) Insert a sectioning command.

Determine the type of section to be inserted, by the argument arg.

• If arg is nil or missing, use the current level.
• If arg is a list (selected by C-u), go downward one level.
• If arg is negative, go up that many levels.
• If arg is positive or zero, use absolute level:
  • + 0 : part
  • + 1 : chapter
  • + 2 : section
  • + 3 : subsection
  • + 4 : subsubsection
  • + 5 : paragraph
  • + 6 : subparagraph

The following variables can be set to customize the function.

LaTeX-section-hook

Hooks to be run when inserting a section.

LaTeX-section-label

Prefix to all section references.

The precise behavior of LaTeX-section is defined by the contents of LaTeX-section-hook.

User Option: LaTeX-section-hook

List of hooks to run when a new section is inserted.

The following variables are set before the hooks are run

level

Numeric section level, default set by prefix arg to LaTeX-section.

name

Name of the sectioning command, derived from level.

title

The title of the section, default to an empty string.

toc

Entry for the table of contents list, default nil.

done-mark

Position of point afterwards, default nil meaning after the inserted text.

A number of hooks are already defined. Most likely, you will be able to get the desired functionality by choosing from these hooks.

LaTeX-section-heading

Query the user about the name of the sectioning command. Modifies level and name.

LaTeX-section-title

Query the user about the title of the section. Modifies title.

LaTeX-section-toc

Query the user for the toc entry. Modifies toc.

LaTeX-section-section

Insert LaTeX section command according to name, title, and toc. If toc is nil, no toc entry is inserted. If toc or title are empty strings, done-mark will be placed at the point they should be inserted.

LaTeX-section-label

Insert a label after the section command. Controlled by the variable LaTeX-section-label.

To get a full featured LaTeX-section command, insert

(setq LaTeX-section-hook '(LaTeX-section-heading LaTeX-section-title LaTeX-section-toc LaTeX-section-section LaTeX-section-label))

in your ‘.emacs’ file.

The behavior of LaTeX-section-label is determined by the variable LaTeX-section-label.

User Option: LaTeX-section-label

Default prefix when asking for a label.

If it is a string, it is used unchanged for all kinds of sections. If it is nil, no label is inserted. If it is a list, the list is searched for a member whose car is equal to the name of the sectioning c