6 @AUCTeX{} is a powerful program offering many features and configuration
7 options. If you are new to @AUCTeX{} this might be deterrent.
8 Fortunately you do not have to learn everything at once. This Quick
9 Start Guide will give you the knowledge of the most important commands
10 and enable you to prepare your first @LaTeX{} document with @AUCTeX{}
11 after only a few minutes of reading.
13 In this introduction, we assume that @AUCTeX{} is already installed on
14 your system. If this is not the case, you should read the file
15 @file{INSTALL} in the base directory of the unpacked distribution
16 tarball. These installation instructions are available in this manual
17 as well, @ref{Installation}. We also assume that you are familiar with
18 the way keystrokes are written in Emacs manuals. If not, have a look at
19 the Emacs Tutorial in the Help menu.
21 If @AUCTeX{} is installed, you might still need to activate it, by
25 (load "auctex.el" nil t t)
28 in your user init file.@footnote{This usually is a file in your home
29 directory called @file{.emacs} if you are utilizing GNU Emacs or
30 @file{.xemacs/init.el} if you are using XEmacs.} In order to get
31 support for many of the @LaTeX{} packages you will use in your
32 documents, you should enable document parsing as well, which can be
36 (setq TeX-auto-save t)
37 (setq TeX-parse-self t)
40 into your init file. Finally, if you often use @code{\include} or
41 @code{\input}, you should make @AUCTeX{} aware of the multi-file
42 document structure. You can do this by inserting
45 (setq-default TeX-master nil)
48 into your init file. Each time you open a new file, @AUCTeX{} will then
49 ask you for a master file.
52 * Editing Facilities:: Functions for editing TeX files
53 * Processing Facilities:: Creating and viewing output, debugging
57 This Quick Start Guide covers two main topics: First we explain how
58 @AUCTeX{} helps you in editing your input file for @TeX{}, @LaTeX{}, and
59 some other formats. Then we describe the functions that @AUCTeX{}
60 provides for processing the input files with @LaTeX{}, Bib@TeX{}, etc.,
61 and for viewing and debugging.
64 @node Editing Facilities
65 @section Functions for editing TeX files
67 @subsection Making your @TeX{} code more readable
69 @AUCTeX{} can do syntax highlighting of your source code, that means
70 commands will get special colors or fonts. You can enable it locally by
71 typing @kbd{M-x font-lock-mode RET}. If you want to have font locking
72 activated generally, enable @code{global-font-lock-mode}, e.g. with
73 @kbd{M-x customize-variable RET global-font-lock-mode RET}.
75 @AUCTeX{} will indent new lines to indicate their syntactical
76 relationship to the surrounding text. For example, the text of a
77 @code{\footnote} or text inside of an environment will be indented
78 relative to the text around it. If the indenting has gotten wrong after
79 adding or deleting some characters, use @key{TAB} to reindent the line,
80 @kbd{M-q} for the whole paragraph, or @kbd{M-x LaTeX-fill-buffer RET}
83 @subsection Entering sectioning commands
87 @cindex @code{\chapter}
88 @cindex @code{\section}
89 @cindex @code{\subsection}
92 Insertion of sectioning macros, that is @samp{\chapter},
93 @samp{\section}, @samp{\subsection}, etc. and accompanying @samp{\label}
94 commands may be eased by using @kbd{C-c C-s}. You will be asked for the
95 section level. As nearly everywhere in @AUCTeX{}, you can use the
96 @key{TAB} or @key{SPC} key to get a list of available level names, and
97 to auto-complete what you started typing. Next, you will be asked for
98 the printed title of the section, and last you will be asked for a label
99 to be associated with the section.
101 @subsection Inserting environments
103 Similarly, you can insert environments, that is
104 @samp{\begin@{@}}--@samp{\end@{@}} pairs: Type @kbd{C-c C-e}, and select
105 an environment type. Again, you can use @key{TAB} or @key{SPC} to get a
106 list, and to complete what you type. Actually, the list will not only
107 provide standard @LaTeX{} environments, but also take your
108 @samp{\documentclass} and @samp{\usepackage} commands into account if
109 you have parsing enabled by setting @code{TeX-parse-self} to @code{t}.
110 If you use a couple of environments frequently, you can use the up and
111 down arrow keys (or @kbd{M-p} and @kbd{M-n}) in the minibuffer to get
112 back to the previously inserted commands.
114 Some environments need additional arguments. Often, @AUCTeX{} knows about
115 this and asks you to enter a value.
117 @subsection Inserting macros
119 @kbd{C-c C-m}, or simply @kbd{C-c RET} will give you a prompt that asks
120 you for a @LaTeX{} macro. You can use @key{TAB} for completion, or the
121 up/down arrow keys (or @kbd{M-p} and @kbd{M-n}) to browse the command
122 history. In many cases, @AUCTeX{} knows which arguments a macro needs
123 and will ask you for that. It even can differentiate between mandatory
124 and optional arguments---for details, see @ref{Completion}.
126 An additional help for inserting macros is provided by the possibility
127 to complete macros right in the buffer. With point at the end of a
128 partially written macro, you can complete it by typing @kbd{M-TAB}.
130 @subsection Changing the font
132 @AUCTeX{} provides convenient keyboard shortcuts for inserting macros
133 which specify the font to be used for typesetting certain parts of the
134 text. They start with @kbd{C-c C-f}, and the last @kbd{C-} combination
135 tells @AUCTeX{} which font you want:
140 @cindex @code{\textbf}
141 Insert @b{bold face} @samp{\textbf@{@point{}@}} text.
145 @cindex @code{\textit}
146 Insert @i{italics} @samp{\textit@{@point{}@}} text.
151 Insert @i{emphasized} @samp{\emph@{@point{}@}} text.
155 @cindex @code{\textsl}
156 Insert @i{slanted} @samp{\textsl@{@point{}@}} text.
160 @cindex @code{\textrm}
161 Insert roman @r{\textrm@{@point{}@}} text.
165 @cindex @code{\textsf}
166 Insert @sans{sans serif} @samp{\textsf@{@point{}@}} text.
170 @cindex @code{\texttt}
171 Insert @t{typewriter} @samp{\texttt@{@point{}@}} text.
175 @cindex @code{\textsc}
176 Insert @sc{small caps} @samp{\textsc@{@point{}@}} text.
180 @cindex Deleting fonts
181 Delete the innermost font specification containing point.
185 If you want to change font attributes of existing text, mark it as a
186 region, and then invoke the commands. If no region is selected, the
187 command will be inserted with empty braces, and you can start typing the
190 Most of those commands will also work in math mode, but then macros like
191 @code{\mathbf} will be inserted.
194 @subsection Other useful features
196 @AUCTeX{} also tries to help you when inserting the right ``quote''
197 signs for your language, dollar signs to typeset math, or pairs of
198 braces. It offers shortcuts for commenting out text (@kbd{C-c ;} for
199 the current region or @kbd{C-c %} for the paragraph you are in). The
200 same keystrokes will remove the % signs, if the region or paragraph is
201 commented out yet. With @code{TeX-fold-mode}, you can hide certain
202 parts (like footnotes, references etc.) that you do not edit currently.
203 Support for Emacs' outline mode is provided as well. And there's more,
204 but this is beyond the scope of this Quick Start Guide.
208 @node Processing Facilities
209 @section Creating and viewing output, debugging
211 @subsection One Command for @LaTeX{}, helpers, viewers, and printing
213 If you have typed some text and want to run @LaTeX{} (or @TeX{}, or
214 other programs---see below) on it, type @kbd{C-c C-c}. If applicable,
215 you will be asked whether you want to save changes, and which program
216 you want to invoke. In many cases, the choice that @AUCTeX{} suggests
217 will be just what you want: first @command{latex}, then a viewer. If a
218 @command{latex} run produces or changes input files for
219 @command{makeindex}, the next suggestion will be to run that program,
220 and @AUCTeX{} knows that you need to run @command{latex} again
221 afterwards---the same holds for Bib@TeX{}.
223 When no processor invocation is necessary anymore, @AUCTeX{} will
224 suggest to run a viewer, or you can chose to create a PostScript file
225 using @command{dvips}, or to directly print it.
227 At this place, a warning needs to be given: First, although @AUCTeX{} is
228 really good in detecting the standard situations when an additional
229 @command{latex} run is necessary, it cannot detect it always. Second,
230 the creation of PostScript files or direct printing currently only works
231 when your output file is a @acronym{DVI} file, not a @acronym{PDF} file.
233 Ah, you didn't know you can do both? That brings us to the next topic.
235 @subsection Choosing an output format
237 From a @LaTeX{} file, you can produce @acronym{DVI} output, or a
238 @acronym{PDF} file directly @i{via} @command{pdflatex}. You can switch
239 on source specials for easier navigation in the output file, or tell
240 @command{latex} to stop after an error (usually @code{\noninteractive}
241 is used, to allow you to detect all errors in a single run).
243 These options are controlled by toggles, the keystrokes should be easy
247 @item @kbd{C-c C-t C-p}
248 This command toggles between @acronym{DVI} and @acronym{PDF} output
250 @item @kbd{C-c C-t C-i}
251 toggles interactive mode
253 @item @kbd{C-c C-t C-s}
254 toggles source specials support
256 @item @kbd{C-c C-t C-o}
257 toggles usage of Omega/lambda.
261 @subsection Debugging @LaTeX{}
263 When @AUCTeX{} runs a program, it creates an output buffer in which it
264 displays the output of the command. If there is a syntactical error in
265 your file, @command{latex} will not complete successfully. @AUCTeX{}
266 will tell you that, and you can get to the place where the first error
267 occured by pressing @kbd{C-c `} (the last character is a backtick). The
268 view will be split in two windows, the output will be displayed in the
269 lower buffer, and both buffers will be centered around the place where
270 the error ocurred. You can then try to fix it in the document buffer,
271 and use the same keystrokes to get to the next error. This procedure
272 may be repeated until all errors have been dealt with. By pressing
273 @kbd{C-c C-w} (@code{TeX-toggle-debug-boxes}) you can toggle whether
274 @AUCTeX{} should notify you of overfull and underfull boxes in addition
277 If a command got stuck in a seemingly infinite loop, or you want to stop
278 execution for other reasons, you can use @kbd{C-c C-k} (for ``kill'').
279 Similar to @kbd{C-l}, which centers the buffer you are in around your
280 current position, @kbd{C-c C-l} centers the output buffer so that the
281 last lines added at the bottom become visible.
283 @subsection Running @LaTeX{} on parts of your document
285 If you want to check how some part of your text looks like, and do not
286 want to wait until the whole document has been typeset, then mark it as
287 a region and use @kbd{C-c C-r}. It behaves just like @kbd{C-c C-c}, but
288 it only uses the document preamble and the region you marked.
290 If you are using @code{\include} or @code{\input} to structure your
291 document, try @kbd{C-c C-b} while you are editing one of the included
292 files. It will run @command{latex} only on the current buffer, using the
293 preamble from the master file.
294 @c does this also work with input? why not?
298 @c TeX-master: "auctex"