| • Summary | Overview of AUCTeX | |
| • Installation | Installing AUCTeX | |
| • Quick Start | Quick Start |
Next: Installation, 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 Installation, or Installation under MS Windows, respectively.
If you are considering upgrading AUCTeX, the recent changes are described in Changes.
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: Summary, 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. This installation procedure has several advantages. Besides being platform and OS independent, you will receive intermediate 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.
| • Prerequisites | ||
| • Configure | ||
| • Build/install and uninstall | ||
| • Loading the package | ||
| • Advice for package providers | ||
| • Advice for non-privileged users | ||
| • Installation under MS Windows | ||
| • Customizing |
Next: Configure, Up: Installation [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 for its operation in DVI mode. The default configuration of AUCTeX is tailored for teTeX or TeXlive-based distributions, but can be adapted easily.
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).
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.
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 Known problems in the preview-latex manual.
Next: Build/install and uninstall, Previous: Prerequisites, Up: Installation [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=/usr/localAll 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 Advice for package providers for detail.
If you are planning to install the package as a single non-priviledged user, you will typically set prefix to your home directory. Consult Advice for non-privileged users for addtional instructions.
--with-emacs[=/path/to/emacs]If you are using a pretest which isn’t in your $PATH, or
configure is not finding the right Emacs executable, you can
specify it with this option.
--with-lispdir=/dirThis 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.elThis 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=auctexThis is the directory where the bulk of the package gets located. The startfile adds this into load-path.
--with-auto-dir=/dirYou 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.
--helpThis 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-previewThis 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-dirThis 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=/dirIf 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=/dirThis 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: Installation [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: Advice for package providers, Previous: Build/install and uninstall, Up: Installation [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.
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 Advice for package providers.
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-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.
Next: Advice for non-privileged users, Previous: Loading the package, Up: Installation [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: Advice for package providers, Up: Installation [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.
Next: Customizing, Previous: Advice for non-privileged users, Up: Installation [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-hierarchywhich 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-emacsif 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-lispThis 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/directoryIf 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:/dirDirectory containing automatically generated information. You should not normally need to set this, as ‘--prefix’ should take care of this.
--disable-previewUse this option if your Emacs version is unable to support image display.
--with-texmf-dir=drive:/dirThis 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.
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: Installation [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 variables with a special significance. They are accessible directly by typing M-x customize-variable RET <variable> 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: Installation, 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, Installation. 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 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.
| • Editing Facilities | Functions for editing TeX files | |
| • Processing Facilities | Creating and viewing output, debugging |
Next: Processing Facilities, Up: Quick Start [Contents][Index]
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.
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: Editing Facilities, 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 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. If you want to go by this
route, when TeX-PDF-via-dvips-ps2pdf variable is non-nil,
AUCTeX will suggest you to run the appropriate command when you type
C-C C-c. For details, see Processor Options.
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.
Previous: Editing Facilities, Up: Quick Start [Contents][Index]