Next: Editing the Document Source, Previous: Copying, Up: AUCTeX [Contents][Index]
Next: Installing AUCTeX, Up: Introduction [Contents][Index]
AUCTeX is a comprehensive customizable integrated environment for writing input files for TeX, LaTeX, ConTeXt, Texinfo, and docTeX using Emacs.
It supports you in the insertion of macros, environments, and sectioning commands by providing completion alternatives and prompting for parameters. It automatically indents your text as you type it and lets you format a whole file at once. The outlining and folding facilities provide you with a focused and clean view of your text.
AUCTeX 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.
More detailed information about the features and usage of AUCTeX can be found in the remainder of this manual.
AUCTeX is written entirely in Emacs Lisp, and hence you can easily add new features for your own needs. It is a GNU project and distributed under the ‘GNU General Public License Version 3’.
The most recent version is always available at https://ftp.gnu.org/pub/gnu/auctex/.
WWW users may want to check out the AUCTeX page at https://www.gnu.org/software/auctex/.
For comprehensive information about how to install AUCTeX See Installing AUCTeX, or Installation under MS Windows, respectively.
If you are considering upgrading AUCTeX, the recent changes are described in Changes and New Features.
If you want to discuss AUCTeX with other users or its developers, there are several mailing lists you can use.
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.
Next: Quick Start, Previous: Overview of AUCTeX, Up: Introduction [Contents][Index]
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. Once the installation is completed, you can skip the rest of this section and proceed to Quick Start.
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 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 Installation under MS Windows.
Next: Configure, Up: Installing AUCTeX [Contents][Index]
Using preview-latex requires a version of Emacs compiled with image support.
Precompiled versions are available from https://ftp.gnu.org/gnu/emacs/windows/.
For an overview of precompiled versions of Emacs for macOS see for example https://www.emacswiki.org/emacs/EmacsForMacOS.
Most GNU/Linux distributions nowadays provide a recent variant of Emacs via their package repositories.
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.
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.
This is needed for operation of preview-latex in both DVI and PDF mode. Ghostscript version 7.07 or newer is required.
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.
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 Known problems in the preview-latex manual.
Next: Build/install and uninstall, Previous: Prerequisites, Up: Installing AUCTeX [Contents][Index]
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 Providing AUCTeX as a package 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 Installation 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.
Next: Loading the package, Previous: Configure, Up: Installing AUCTeX [Contents][Index]
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.
Next: Providing AUCTeX as a package, Previous: Build/install and uninstall, Up: Installing AUCTeX [Contents][Index]
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 See Providing AUCTeX as a package.
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.
Next: Installation for non-privileged users, Previous: Loading the package, Up: Installing AUCTeX [Contents][Index]
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.
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:
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.
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:
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’.
Next: Installation under MS Windows, Previous: Providing AUCTeX as a package, Up: Installing AUCTeX [Contents][Index]
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 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:
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.
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"))
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.
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)
Next: Customizing, Previous: Installation for non-privileged users, Up: Installing AUCTeX [Contents][Index]
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.
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'
The commands above is example 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:
make
In case there were, please refer to the detailed description below.
make install
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:
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.
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.
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.
\n
when reading text files,
you’ll run into trouble.
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 automatically; if this doesn’t
happen, try --with-emacs 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-lispdir=drive:/path/to/site-lisp
This 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.
--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.
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.
make
in the installation directory.
make install
in the installation directory.
(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 or ~/.emacs.d/init.el from within Emacs).
The default configuration of AUCTeX is probably not the best fit for Windows systems with MiKTeX. You might want to add
(require 'tex-mik)
after loading auctex.el and preview-latex.el in order to get more appropriate values for some customization options.
You can always use
M-x customize-group RET AUCTeX RET
in order to customize more stuff, or use the ‘Customize’ menu.
If this barfs and tells you that image type ‘png’ is not supported, you can either add PNG support to your Emacs installation or choose another image format to be used by preview-latex.
Adding support for an image format usually involves the installation of a library, e.g. from http://gnuwin32.sf.net/. If you got your Emacs from https://www.gnu.org/ you might want to check its README file for details.
A different image format can be chosen by setting the variable
preview-image-type
. While it is recommended to keep the
‘dvipng’ or ‘png’ setting, you can temporarily select a
different format like ‘pnm’ to check if the lack of PNG
support is the only problem with your Emacs installation.
Try adding the line
(setq preview-image-type 'pnm)
to your init file for a quick test. You should remove the line after the test again, because PNM files take away vast amounts of disk space, and thus also of load/save time.
Well, that about is all. Have fun!
Previous: Installation under MS Windows, Up: Installing AUCTeX [Contents][Index]
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.
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.
Previous: Installing AUCTeX, Up: Introduction [Contents][Index]
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 in any other way than from the Emacs package manager (ELPA), you might still need to activate it, by inserting
(load "auctex.el" nil t t)
in your user init file.1
If AUCTeX is installed from ELPA, the installation procedure already cares about loading AUCTeX correctly and you must not have the line above in your init file. Note that this also applies if you have the following line in your init file
(package-initialize)
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 multifile
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.
Next: Creating and viewing output, debugging, Up: Quick Start [Contents][Index]
AUCTeX can do syntax highlighting of your source code, that means commands will get special colors or fonts. This is enabled by default. You can disable it locally by typing M-x 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.
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.
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.
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.
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:
Insert bold face ‘\textbf{∗}’ text.
Insert italics ‘\textit{∗}’ text.
Insert emphasized ‘\emph{∗}’ text.
Insert slanted ‘\textsl{∗}’ text.
Insert roman ‘\textrm{∗}’ text.
Insert sans serif ‘\textsf{∗}’ text.
Insert typewriter ‘\texttt{∗}’ text.
Insert SMALL CAPS ‘\textsc{∗}’ text.
Delete the innermost font specification containing point.
If you want to change font attributes of existing text, mark it as an active 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.
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.
Previous: Functions for editing TeX files, Up: Quick Start [Contents][Index]
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.
Actually, there is another command which comes in handy to compile
documents: type C-c C-a (TeX-command-run-all
) and AUCTeX
will compile the document for you until it is ready and then run the
viewer. This is the same as issuing repeatedly C-c C-c and
letting AUCTeX guess the next command to run.
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.
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:
This command toggles between DVI and PDF output
toggles interactive mode
toggles SyncTeX (or source specials) support
toggles usage of Omega/lambda.
There is also another possibility: compile the document with
tex
(or latex
) and then convert the resulting
DVI file to PDF using
dvips
–ps2pdf
sequence or dvipdfmx
command.
If you want to go by this route, customize TeX-PDF-from-DVI
option.
Then AUCTeX will suggest you to run the appropriate command when
you type C-C C-c. For details, see Options for TeX Processors.
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.
Issue M-x TeX-error-overview RET to see a nicely formatted list of all errors and warnings reported by the compiler.
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.
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.
Next: Editing the Document Source, Previous: Copying, Up: AUCTeX [Contents][Index]