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

(require 'tex-site)

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 5.2 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 @iftex {@textsf sans serif}@c sans serif@c

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.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.