2 @comment %**start of header
3 @setfilename auctex.info
5 @settitle AUCTeX @value{VERSION}
6 @c footnotestyle separate
8 @comment %**end of header
11 This manual is for @AUCTeX{}
12 (version @value{VERSION} from @value{UPDATED}),
13 a sophisticated TeX environment for Emacs.
15 Copyright @copyright{} 1992, 1993, 1994, 1995, 2001, 2002, 2004, 2005,
16 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.3 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A
23 copy of the license is included in the section entitled ``GNU Free
24 Documentation License.''
30 * AUCTeX: (auctex). A sophisticated TeX environment for Emacs.
34 * AUCTeX: (auctex). A sophisticated TeX environment for Emacs.
38 @tolerance 10000 @emergencystretch 3em
44 @subtitle A sophisticated @TeX{} environment for Emacs
45 @subtitle Version @value{VERSION}, @value{UPDATED}
46 @author Kresten Krab Thorup
47 @author Per Abrahamsen
48 @author David Kastrup and others
50 @vskip 0pt plus 1filll
54 @c Use @ifinfo _and_ @ifhtml here because Texinfo 3 cannot cope with
55 @c @ifnottex around a top node.
60 This manual may be copied under the conditions spelled out in
61 @ref{Copying this Manual}.
73 @unnumbered Executive Summary
76 @AUCTeX{} is an integrated environment for editing @LaTeX{}, @ConTeXt{},
77 doc@TeX{}, Texinfo, and @TeX{} files.
79 Although @AUCTeX{} contains a large number of features, there are no
80 reasons to despair. You can continue to write @TeX{} and @LaTeX{}
81 documents the way you are used to, and only start using the multiple
82 features in small steps. @AUCTeX{} is not monolithic, each feature
83 described in this manual is useful by itself, but together they provide
84 an environment where you will make very few @LaTeX{} errors, and makes it
85 easy to find the errors that may slip through anyway.
87 It is a good idea to make a printout of @AUCTeX{}'s reference card
88 @file{tex-ref.tex} or one of its typeset versions.
90 If you want to make @AUCTeX{} aware of style files and multi-file
91 documents right away, insert the following in your @file{.emacs} file.
94 (setq TeX-auto-save t)
95 (setq TeX-parse-self t)
96 (setq-default TeX-master nil)
99 Another thing you should enable is Ref@TeX{}, a comprehensive solution
100 for managing cross references, bibliographies, indices, document
101 navigation and a few other things. (@pxref{Installation,,,reftex,The
104 For detailed information about the @previewlatex{} subsystem of
105 @AUCTeX{}, see @ref{Top,,Introduction,preview-latex,The @previewlatex{}
108 There is a mailing list for general discussion about @AUCTeX{}: write a
109 mail with ``subscribe'' in the subject to
110 @email{auctex-request@@gnu.org} to join it. Send contributions to
111 @email{auctex@@gnu.org}.
113 Bug reports should go to @email{bug-auctex@@gnu.org}, suggestions for
114 new features, and pleas for help should go to either
115 @email{auctex-devel@@gnu.org} (the @AUCTeX{} developers), or to
116 @email{auctex@@gnu.org} if they might have general interest. Please use
117 the command @kbd{M-x TeX-submit-bug-report RET} to report bugs if
118 possible. You can subscribe to a low-volume announcement list by
119 sending ``subscribe'' in the subject of a mail to
120 @email{info-auctex-request@@gnu.org}.
124 * Introduction:: Introduction to @AUCTeX{}
125 * Editing:: Editing the Document Source
126 * Display:: Controlling Screen Display
127 * Processing:: Starting Processors, Viewers and Other Programs
128 * Customization:: Customization and Extension
129 * Appendices:: Copying, Changes, Development, FAQ
133 --- The Detailed Node Listing ---
137 * Summary:: Overview of @AUCTeX{}
138 * Installation:: Installing @AUCTeX{}
139 * Quick Start:: Quick Start
141 Editing the Document Source
143 * Quotes:: Inserting double quotes
144 * Font Specifiers:: Inserting Font Specifiers
145 * Sectioning:: Inserting chapters, sections, etc.
146 * Environments:: Inserting Environment Templates
147 * Mathematics:: Entering Mathematics
148 * Completion:: Completion of macros
149 * Commenting:: Commenting text
150 * Indenting:: Reflecting syntactic constructs with whitespace
151 * Filling:: Automatic and manual line breaking
153 Inserting Environment Templates
155 * Equations:: Equations
157 * Itemize-like:: Itemize-like Environments
158 * Tabular-like:: Tabular-like Environments
159 * Customizing Environments:: Customizing Environments
161 Controlling Screen Display
163 * Font Locking:: Font Locking
164 * Folding:: Folding Macros and Environments
165 * Outline:: Outlining the Document
169 * Fontification of macros:: Fontification of macros
170 * Fontification of quotes:: Fontification of quotes
171 * Fontification of math:: Fontification of math constructs
172 * Verbatim content:: Verbatim macros and environments
173 * Faces:: Faces used by font-latex
175 Starting Processors, Viewers and Other Programs
177 * Commands:: Invoking external commands.
178 * Viewing:: Invoking external viewers.
179 * Debugging:: Debugging @TeX{} and @LaTeX{} output.
180 * Checking:: Checking the document.
181 * Control:: Controlling the processes.
182 * Cleaning:: Cleaning intermediate and output files.
183 * Documentation:: Documentation about macros and packages.
185 Viewing the Formatted Output
187 * Starting Viewers:: Starting viewers
188 * I/O Correlation:: Forward and inverse search
190 Customization and Extension
192 * Multifile:: Multifile Documents
193 * Parsing Files:: Automatic Parsing of @TeX{} Files
194 * Internationalization:: Language Support
195 * Automatic:: Automatic Customization
196 * Style Files:: Writing Your Own Style Support
200 * European:: Using @AUCTeX{} with European Languages
201 * Japanese:: Using @AUCTeX{} with Japanese
203 Automatic Customization
205 * Automatic Global:: Automatic Customization for the Site
206 * Automatic Private:: Automatic Customization for a User
207 * Automatic Local:: Automatic Customization for a Directory
209 Writing Your Own Style Support
211 * Simple Style:: A Simple Style File
212 * Adding Macros:: Adding Support for Macros
213 * Adding Environments:: Adding Support for Environments
214 * Adding Other:: Adding Other Information
215 * Hacking the Parser:: Automatic Extraction of New Things
217 Copying, Changes, Development, FAQ
219 * Copying this Manual::
226 * GNU Free Documentation License:: License for copying this manual.
243 @cindex General Public License
246 @cindex Free software
251 @c This text adapted from the Texinfo 2.16 distribution.
253 @AUCTeX{} primarily consists of Lisp files for Emacs (and XEmacs), but
254 there are also installation scripts and files and @TeX{} support files.
255 All of those are @dfn{free}; this means that everyone is free to use
256 them and free to redistribute them on a free basis. The files of
257 @AUCTeX{} are not in the public domain; they are copyrighted and there
258 are restrictions on their distribution, but these restrictions are
259 designed to permit everything that a good cooperating citizen would want
260 to do. What is not allowed is to try to prevent others from further
261 sharing any version of these programs that they might get from you.
263 Specifically, we want to make sure that you have the right to give away
264 copies of the files that constitute @AUCTeX{}, that you receive source
265 code or else can get it if you want it, that you can change these files
266 or use pieces of them in new free programs, and that you know you can do
269 To make sure that everyone has such rights, we have to forbid you to
270 deprive anyone else of these rights. For example, if you distribute
271 copies of parts of @AUCTeX{}, you must give the recipients all the
272 rights that you have. You must make sure that they, too, receive or can
273 get the source code. And you must tell them their rights.
275 Also, for our own protection, we must make certain that everyone finds
276 out that there is no warranty for @AUCTeX{}. If any parts are modified
277 by someone else and passed on, we want their recipients to know that
278 what they have is not what we distributed, so that any problems
279 introduced by others will not reflect on our reputation.
281 The precise conditions of the licenses for the files currently being
282 distributed as part of @AUCTeX{} are found in the General Public
283 Licenses that accompany them. This manual specifically is covered by
284 the GNU Free Documentation License (@pxref{Copying this Manual}).
287 @chapter Introduction
290 * Summary:: Overview of @AUCTeX{}
291 * Installation:: Installing @AUCTeX{}
292 * Quick Start:: Quick Start
298 @include install.texi
300 @include quickstart.texi
304 @chapter Editing the Document Source
306 The most commonly used commands/macros of @AUCTeX{} are those which
307 simply insert templates for often used @TeX{}, @LaTeX{}, or @ConTeXt{}
308 constructs, like font changes, handling of environments, etc. These
309 features are very simple, and easy to learn, and help you avoid mistakes
310 like mismatched braces, or @samp{\begin@{@}}-@samp{\end@{@}} pairs.
312 Apart from that this chapter contains a description of some features for
313 entering more specialized sorts of text, for formatting the source by
314 indenting and filling and for navigating through the document.
317 * Quotes:: Inserting double quotes
318 * Font Specifiers:: Inserting Font Specifiers
319 * Sectioning:: Inserting chapters, sections, etc.
320 * Environments:: Inserting Environment Templates
321 * Mathematics:: Entering Mathematics
322 * Completion:: Completion of macros
323 * Commenting:: Commenting text
324 * Indenting:: Reflecting syntactic constructs with whitespace
325 * Filling:: Automatic and manual line breaking
329 @section Insertion of Quotes, Dollars, and Braces
332 @cindex Double quotes
336 @cindex Math mode delimiters
337 @cindex Matching dollar signs
338 @cindex Display math mode
340 @subheading Quotation Marks
342 In @TeX{}, literal double quotes @samp{"like this"} are seldom used,
343 instead two single quotes are used @samp{``like this''}. To help you
344 insert these efficiently, @AUCTeX{} allows you to continue to press
345 @kbd{"} to insert two single quotes. To get a literal double quote,
348 @deffn Command TeX-insert-quote @var{count}
350 (@kbd{"}) Insert the appropriate quote marks for @TeX{}.
352 Inserts the value of @code{TeX-open-quote} (normally @samp{``}) or
353 @code{TeX-close-quote} (normally @samp{''}) depending on the context.
354 With prefix argument, always inserts @samp{"} characters.
357 @defopt TeX-open-quote
358 String inserted by typing @kbd{"} to open a quotation.
359 (@xref{European}, for language-specific quotation mark insertion.)
362 @defopt TeX-close-quote
363 String inserted by typing @kbd{"} to close a quotation.
364 (@xref{European}, for language-specific quotation mark insertion.)
367 @defopt TeX-quote-after-quote
368 Determines the behavior of @kbd{"}. If it is non-nil, typing @kbd{"}
369 will insert a literal double quote. The respective values of
370 @code{TeX-open-quote} and @code{TeX-close-quote} will be inserted
371 after typing @kbd{"} once again.
374 The @samp{babel} package provides special support for the requirements
375 of typesetting quotation marks in many different languages. If you use
376 this package, either directly or by loading a language-specific style
377 file, you should also use the special commands for quote insertion
378 instead of the standard quotes shown above. @AUCTeX{} is able to
379 recognize several of these languages and will change quote insertion
380 accordingly. @xref{European}, for details about this feature and how to
383 @vindex LaTeX-csquotes-open-quote
384 @vindex LaTeX-csquotes-close-quote
385 @vindex LaTeX-csquotes-quote-after-quote
386 In case you are using the @samp{csquotes} package, you should customize
387 @code{LaTeX-csquotes-open-quote}, @code{LaTeX-csquotes-close-quote} and
388 @code{LaTeX-csquotes-quote-after-quote}. The quotation characters will
389 only be used if both variables---@code{LaTeX-csquotes-open-quote} and
390 @code{LaTeX-csquotes-close-quote}---are non-empty strings. But then the
391 @samp{csquotes}-related values will take precedence over the
392 language-specific ones.
394 @subheading Dollar Signs
396 In @AUCTeX{}, dollar signs should match like they do in @TeX{}. This
397 has been partially implemented, we assume dollar signs always match
398 within a paragraph. The first @samp{$} you insert in a paragraph will
399 do nothing special. The second @samp{$} will match the first. This
400 will be indicated by moving the cursor temporarily over the first dollar
403 @deffn Command TeX-insert-dollar @var{arg}
405 (@kbd{$}) Insert dollar sign.
407 Show matching dollar sign if this dollar sign end the @TeX{} math mode.
408 Ensure double dollar signs match up correctly by inserting extra dollar
409 signs when needed if @code{TeX-math-close-double-dollar} is non-nil.
411 With optional @var{arg}, insert that many dollar signs.
414 @defopt TeX-math-close-double-dollar
415 Control the insertion of double dollar signs for delimiting display
416 math. (Note that you should not use double dollar signs in @LaTeX{}
417 because this practice can lead to wrong spacing in typeset documents.)
418 If the variable is non-nil and you enter a dollar sign that matches a
419 double dollar sign @samp{$$} @AUCTeX{} will automatically insert two
425 To avoid unbalanced braces, it is useful to insert them pairwise. You
426 can do this by typing @kbd{C-c @{}.
428 @deffn Command TeX-insert-braces
430 (@kbd{C-c @{}) Make a pair of braces and position the cursor
431 to type inside of them. If there is an active region, put braces around
432 it and leave point after the closing brace.
435 @node Font Specifiers
436 @section Inserting Font Specifiers
440 @cindex Changing font
441 @cindex Specifying a font
443 Perhaps the most used keyboard commands of @AUCTeX{} are the short-cuts
444 available for easy insertion of font changing macros.
446 If you give an argument (that is, type @kbd{C-u}) to the font command,
447 the innermost font will be replaced, i.e. the font in the @TeX{} group
448 around point will be changed. The following table shows the available
449 commands, with @code{@point{}} indicating the position where the text
455 @cindex @code{\textbf}
456 Insert @b{bold face} @samp{\textbf@{@point{}@}} text.
460 @cindex @code{\textit}
461 Insert @i{italics} @samp{\textit@{@point{}@}} text.
466 Insert @i{emphasized} @samp{\emph@{@point{}@}} text.
470 @cindex @code{\textsl}
471 Insert @i{slanted} @samp{\textsl@{@point{}@}} text.
475 @cindex @code{\textrm}
476 Insert roman @r{\textrm@{@point{}@}} text.
480 @cindex @code{\textsf}
481 Insert @sans{sans serif} @samp{\textsf@{@point{}@}} text.
485 @cindex @code{\texttt}
486 Insert @t{typewriter} @samp{\texttt@{@point{}@}} text.
490 @cindex @code{\textsc}
491 Insert @sc{small caps} @samp{\textsc@{@point{}@}} text.
495 @cindex Deleting fonts
496 Delete the innermost font specification containing point.
500 @deffn Command TeX-font replace what
502 (@kbd{C-c C-f}) Insert template for font change command.
504 If @var{replace} is not nil, replace current font. @var{what}
505 determines the font to use, as specified by @code{TeX-font-list}.
508 @defopt TeX-font-list
509 List of fonts used by @code{TeX-font}.
511 Each entry is a list with three elements. The first element is the
512 key to activate the font. The second element is the string to insert
513 before point, and the third element is the string to insert after
514 point. An optional fourth element means always replace if not nil.
517 @defopt LaTeX-font-list
518 List of fonts used by @code{TeX-font} in LaTeX mode. It has the same
519 structure as @code{TeX-font-list}.
523 @section Inserting chapters, sections, etc.
527 @cindex @code{\chapter}
528 @cindex @code{\section}
529 @cindex @code{\subsection}
530 @cindex @code{\label}
532 Insertion of sectioning macros, that is @samp{\chapter},
533 @samp{\section}, @samp{\subsection}, etc. and accompanying
534 @samp{\label}'s may be eased by using @kbd{C-c C-s}. This command is
535 highly customizable, the following describes the default behavior.
537 When invoking you will be asked for a section macro to insert. An
538 appropriate default is automatically selected by @AUCTeX{}, that is
539 either: at the top of the document; the top level sectioning for that
540 document style, and any other place: The same as the last occurring
543 Next, you will be asked for the actual name of that section, and
544 last you will be asked for a label to be associated with that section.
545 The label will be prefixed by the value specified in
546 @code{LaTeX-section-hook}.
548 @deffn Command LaTeX-section @var{arg}
550 (@kbd{C-c C-s}) Insert a sectioning command.
552 Determine the type of section to be inserted, by the argument
557 If @var{arg} is nil or missing, use the current level.
559 If @var{arg} is a list (selected by C-u), go downward one level.
561 If @var{arg} is negative, go up that many levels.
563 If @var{arg} is positive or zero, use absolute level:
582 The following variables can be set to customize the function.
585 @item LaTeX-section-hook
586 Hooks to be run when inserting a section.
587 @item LaTeX-section-label
588 Prefix to all section references.
593 The precise behavior of @code{LaTeX-section} is defined by the contents
594 of @code{LaTeX-section-hook}.
596 @defopt LaTeX-section-hook
597 List of hooks to run when a new section is inserted.
599 The following variables are set before the hooks are run
603 Numeric section level, default set by prefix arg to @code{LaTeX-section}.
605 Name of the sectioning command, derived from @var{level}.
607 The title of the section, default to an empty string.
609 Entry for the table of contents list, default nil.
611 Position of point afterwards, default nil meaning after the inserted
615 A number of hooks are already defined. Most likely, you will be able to
616 get the desired functionality by choosing from these hooks.
619 @item LaTeX-section-heading
620 Query the user about the name of the sectioning command. Modifies
621 @var{level} and @var{name}.
622 @item LaTeX-section-title
623 Query the user about the title of the section. Modifies @var{title}.
624 @item LaTeX-section-toc
625 Query the user for the toc entry. Modifies @var{toc}.
626 @item LaTeX-section-section
627 Insert @LaTeX{} section command according to @var{name}, @var{title},
628 and @var{toc}. If @var{toc} is nil, no toc entry is inserted. If
629 @var{toc} or @var{title} are empty strings, @var{done-mark} will be
630 placed at the point they should be inserted.
631 @item LaTeX-section-label
632 Insert a label after the section command. Controlled by the variable
633 @code{LaTeX-section-label}.
636 To get a full featured @code{LaTeX-section} command, insert
639 (setq LaTeX-section-hook
640 '(LaTeX-section-heading
643 LaTeX-section-section
644 LaTeX-section-label))
647 in your @file{.emacs} file.
650 The behavior of @code{LaTeX-section-label} is determined by the
651 variable @code{LaTeX-section-label}.
653 @defopt LaTeX-section-label
654 Default prefix when asking for a label.
656 If it is a string, it is used unchanged for all kinds of sections.
657 If it is nil, no label is inserted.
658 If it is a list, the list is searched for a member whose car is equal
659 to the name of the sectioning command being inserted. The cdr is then
660 used as the prefix. If the name is not found, or if the cdr is nil,
661 no label is inserted.
663 @cindex Prefix for labels
666 By default, chapters have a prefix of @samp{cha:} while sections and
667 subsections have a prefix of @samp{sec:}. Labels are not automatically
668 inserted for other types of sections.
672 @section Inserting Environment Templates
674 @cindex @samp{\begin}
677 A large apparatus is available that supports insertions of environments,
678 that is @samp{\begin@{@}} --- @samp{\end@{@}} pairs.
680 @AUCTeX{} is aware of most of the actual environments available in a
681 specific document. This is achieved by examining your
682 @samp{\documentclass} command, and consulting a precompiled list of
683 environments available in a large number of styles.
685 You insert an environment with @kbd{C-c C-e}, and select an environment
686 type. Depending on the environment, @AUCTeX{} may ask more questions
687 about the optional parts of the selected environment type. With
688 @kbd{C-u C-c C-e} you will change the current environment.
690 @deffn Command LaTeX-environment @var{arg}
692 (@kbd{C-c C-e}) @AUCTeX{} will prompt you for an environment
693 to insert. At this prompt, you may press @key{TAB} or @key{SPC} to
694 complete a partially written name, and/or to get a list of available
695 environments. After selection of a specific environment @AUCTeX{} may
696 prompt you for further specifications.
698 If the optional argument @var{arg} is not-nil (i.e. you have given a
699 prefix argument), the current environment is modified and no new
700 environment is inserted.
703 As a default selection, @AUCTeX{} will suggest the environment last
704 inserted or, as the first choice the value of the variable
705 @code{LaTeX-default-environment}.
707 @defopt LaTeX-default-environment
708 Default environment to insert when invoking @samp{LaTeX-environment}
712 If the document is empty, or the cursor is placed at the top of the
713 document, @AUCTeX{} will default to insert a `document' environment.
715 Most of these are described further in the following sections, and you
716 may easily specify more. @xref{Customizing Environments}.
719 * Equations:: Equations
721 * Itemize-like:: Itemize-like Environments
722 * Tabular-like:: Tabular-like Environments
723 * Customizing Environments:: Customizing Environments
726 You can close the current environment with @kbd{C-c ]}, but we suggest
727 that you use @kbd{C-c C-e} to insert complete environments instead.
729 @deffn Command LaTeX-close-environment
731 (@kbd{C-c ]}) Insert an @samp{\end} that matches the current environment.
735 @subsection Equations
741 When inserting equation-like environments, the @samp{\label} will have a
742 default prefix, which is controlled by the following variables:
744 @defopt LaTeX-equation-label
745 Prefix to use for `equation' labels.
748 @defopt LaTeX-eqnarray-label
749 Prefix to use for `eqnarray' labels.
752 @defopt LaTeX-amsmath-label
753 Prefix to use for amsmath equation labels. Amsmath equations include
754 @samp{align}, @samp{alignat}, @samp{xalignat}, @samp{aligned},
755 @samp{flalign} and @samp{gather}.
762 @cindex Figure environment
764 @cindex Table environment
766 Figures and tables (i.e., floats) may also be inserted using @AUCTeX{}.
767 After choosing either `figure' or `table' in the environment list
768 described above, you will be prompted for a number of additional things.
772 This is the optional argument of float environments that controls how
773 they are placed in the final document. In @LaTeX{} this is a sequence
774 of the letters @samp{htbp} as described in the @LaTeX{} manual. The
775 value will default to the value of @code{LaTeX-float}.
779 This is the caption of the float. The default is to insert the caption
780 at the bottom of the float. You can specify floats where the caption
781 should be placed at the top with @code{LaTeX-top-caption-list}.
782 @vindex LaTeX-top-caption-list
785 The label of this float. The label will have a default prefix, which is
786 controlled by the variables @code{LaTeX-figure-label} and
787 @code{LaTeX-table-label}.
788 @vindex LaTeX-figure-label
789 @vindex LaTeX-table-label
790 @cindex Prefix for labels
795 Moreover, you will be asked if you want the contents of the float
796 environment to be horizontally centered. Upon a positive answer a
797 @samp{\centering} macro will be inserted at the beginning of the float
801 Default placement for floats.
804 @defopt LaTeX-figure-label
805 Prefix to use for figure labels.
808 @defopt LaTeX-table-label
809 Prefix to use for table labels.
812 @defopt LaTeX-top-caption-list
813 List of float environments with top caption.
817 @subsection Itemize-like Environments
824 In an itemize-like environment, nodes (i.e., @samp{\item}s) may be
825 inserted using @kbd{C-c @key{LFD}}.
827 @deffn Command LaTeX-insert-item
828 @kindex C-c @key{LFD}
829 (@kbd{C-c @key{LFD}}) Close the current item, move to the next line and
830 insert an appropriate @samp{\item} for the current environment. That is,
831 `itemize' and `enumerate' will have @samp{\item } inserted, while
832 `description' will have @samp{\item[]} inserted.
836 @subsection Tabular-like Environments
838 When inserting Tabular-like environments, that is, `tabular' `array'
839 etc., you will be prompted for a template for that environment.
842 @defopt LaTeX-default-format
843 Default format string for array and tabular environments.
846 @defopt LaTeX-default-position
847 Default position string for array and tabular environments. If nil,
848 act like the empty string is given, but don't prompt for a position.
851 @node Customizing Environments
852 @subsection Customizing Environments
854 @xref{Adding Environments}, for how to customize the list of known
858 @section Entering Mathematics
861 @cindex Abbreviations
863 @TeX{} is written by a mathematician, and has always contained good
864 support for formatting mathematical text. @AUCTeX{} supports this
865 tradition, by offering a special minor mode for entering text with many
866 mathematical symbols. You can enter this mode by typing @kbd{C-c
869 @deffn Command LaTeX-math-mode
871 (@kbd{C-c ~}) Toggle LaTeX Math mode. This is a minor mode rebinding
872 the key @code{LaTeX-math-abbrev-prefix} to allow easy typing of
873 mathematical symbols. @kbd{`} will read a character from the keyboard,
874 and insert the symbol as specified in @code{LaTeX-math-default} and
875 @code{LaTeX-math-list}. If given a prefix argument, the symbol will be
876 surrounded by dollar signs.
879 You can use another prefix key (instead of @kbd{`}) by setting the
880 variable @code{LaTeX-math-abbrev-prefix}.
882 To enable LaTeX Math mode by default, add the following in your
885 (add-hook 'LaTeX-mode-hook 'LaTeX-math-mode)
888 @defopt LaTeX-math-abbrev-prefix
889 A string containing the prefix of @code{LaTeX-math-mode} commands; This
890 value defaults to @kbd{`}.
892 The string has to be a key or key sequence in a format understood by the
893 @code{kbd} macro. This corresponds to the syntax usually used in the
894 manuals for Emacs Emacs Lisp.
897 The variable @code{LaTeX-math-list} allows you to add your own mappings.
899 @defopt LaTeX-math-list
900 A list containing user-defined keys and commands to be used in LaTeX
901 Math mode. Each entry should be a list of two to four elements.
903 First, the key to be used after @code{LaTeX-math-abbrev-prefix} for
904 macro insertion. If it is nil, the symbol has no associated
905 keystroke (it is available in the menu, though).
907 Second, a string representing the name of the macro (without a leading
910 Third, a string representing the name of a submenu the command should be
911 added to. Use a list of strings in case of nested menus.
913 Fourth, the position of a Unicode character to be displayed in the menu
914 alongside the macro name. This is an integer value.
917 @defopt LaTeX-math-menu-unicode
918 Whether the LaTeX menu should try using Unicode for effect. Your Emacs
919 built must be able to display include Unicode characters in menus for
923 @AUCTeX{}'s reference card @file{tex-ref.tex} includes a list of all
926 @AUCTeX{} can help you write subscripts and superscripts in math
927 constructs by automatically inserting a pair of braces after typing
928 @key{_} or @key{^} respectively and putting point between the braces.
929 In order to enable this feature, set the variable
930 @code{TeX-electric-sub-and-superscript} to a non-nil value.
932 @defopt TeX-electric-sub-and-superscript
933 If non-nil, insert braces after typing @key{^} and @key{_} in math mode.
940 @cindex Macro expansion
941 @cindex Macro completion
942 @cindex Macro arguments
943 @cindex Arguments to @TeX{} macros
945 Emacs lisp programmers probably know the @code{lisp-complete-symbol}
946 command, usually bound to @kbd{M-@key{TAB}}. Users of the wonderful
947 ispell mode know and love the @code{ispell-complete-word} command from
948 that package. Similarly, @AUCTeX{} has a @code{TeX-complete-symbol}
949 command, by default bound to @kbd{M-@key{TAB}} which is equivalent to
950 @kbd{M-C-i}. Using @code{TeX-complete-symbol} makes it easier to type
951 and remember the names of long @LaTeX{} macros.
953 In order to use @code{TeX-complete-symbol}, you should write a backslash
954 and the start of the macro. Typing @kbd{M-@key{TAB}} will now complete
955 as much of the macro, as it unambiguously can. For example, if you type
956 `@samp{\renewc}' and then @kbd{M-@key{TAB}}, it will expand to
957 `@samp{\renewcommand}'.
959 @deffn Command TeX-complete-symbol
961 (@kbd{M-@key{TAB}}) Complete @TeX{} symbol before point.
964 A more direct way to insert a macro is with @code{TeX-insert-macro},
965 bound to @kbd{C-c C-m} which is equivalent to @kbd{C-c @key{RET}}. It
966 has the advantage over completion that it knows about the argument of
967 most standard @LaTeX{} macros, and will prompt for them. It also knows
968 about the type of the arguments, so it will for example give completion
969 for the argument to @samp{\include}. Some examples are listed below.
971 @deffn Command TeX-insert-macro
973 (@kbd{C-c C-m} or @kbd{C-c @key{RET}}) Prompt (with completion) for the
974 name of a @TeX{} macro, and if @AUCTeX{} knows the macro, prompt for
978 As a default selection, @AUCTeX{} will suggest the macro last inserted
979 or, as the first choice the value of the variable
980 @code{TeX-default-macro}.
982 @defopt TeX-insert-macro-default-style
983 Specifies whether @code{TeX-insert-macro} will ask for all optional
986 If set to the symbol @code{show-optional-args}, @code{TeX-insert-macro}
987 asks for optional arguments of @TeX{} macros. If set to
988 @code{mandatory-args-only}, @code{TeX-insert-macro} asks only for
989 mandatory arguments. When @code{TeX-insert-macro} is called with prefix
990 argument (@kbd{C-u}), it's the other way round.
992 Note that for some macros, there are special mechanisms, e.g.
993 @code{LaTeX-includegraphics-options-alist}.
998 @defopt TeX-default-macro
999 Default macro to insert when invoking @code{TeX-insert-macro} first time.
1002 A faster alternative is to bind the function @code{TeX-electric-macro}
1003 to @samp{\}. This can be done by setting the variable
1004 @code{TeX-electric-escape}
1006 @defopt TeX-electric-escape
1007 If this is non-nil when @AUCTeX{} is loaded, the @TeX{} escape
1008 character @samp{\} will be bound to @code{TeX-electric-macro}
1011 The difference between @code{TeX-insert-macro} and
1012 @code{TeX-electric-macro} is that space will complete and exit from the
1013 minibuffer in @code{TeX-electric-macro}. Use @key{TAB} if you merely
1016 @deffn Command TeX-electric-macro
1017 Prompt (with completion) for the name of a @TeX{} macro,
1018 and if @AUCTeX{} knows the macro, prompt for each argument.
1019 Space will complete and exit.
1022 By default @AUCTeX{} will put an empty set braces @samp{@{@}} after a
1023 macro with no arguments to stop it from eating the next whitespace.
1024 This can be stopped by entering @code{LaTeX-math-mode},
1025 @pxref{Mathematics}, or by setting @code{TeX-insert-braces} to nil.
1027 @defopt TeX-insert-braces
1028 If non-nil, append a empty pair of braces after inserting a macro.
1031 Completions work because @AUCTeX{} can analyze @TeX{} files, and store
1032 symbols in Emacs Lisp files for later retrieval. @xref{Automatic}, for
1035 @cindex \cite, completion of
1036 @cindex Bib@TeX{}, completion
1037 @cindex cite, completion of
1038 @cindex bibliography, completion
1039 @cindex citations, completion of
1040 @cindex \label, completion
1041 @cindex \ref, completion
1042 @cindex labels, completion of
1043 @AUCTeX{} will also make completion for many macro arguments, for
1044 example existing labels when you enter a @samp{\ref} macro with
1045 @code{TeX-insert-macro} or @code{TeX-electric-macro}, and Bib@TeX{}
1046 entries when you enter a @samp{\cite} macro. For this kind of
1047 completion to work, parsing must be enabled as described in
1048 @pxref{Parsing Files}. For @samp{\cite} you must also make sure that
1049 the Bib@TeX{} files have been saved at least once after you enabled
1050 automatic parsing on save, and that the basename of the Bib@TeX{} file
1051 does not conflict with the basename of one of @TeX{} files.
1056 It is often necessary to comment out temporarily a region of @TeX{} or
1057 @LaTeX{} code. This can be done with the commands @kbd{C-c ;} and
1058 @kbd{C-c %}. @kbd{C-c ;} will comment out all lines in the current
1059 region, while @kbd{C-c %} will comment out the current paragraph.
1060 Type @kbd{C-c ;} again to uncomment all lines of a commented region,
1061 or @kbd{C-c %} again to uncomment all comment lines around point.
1062 These commands will insert or remove a single @samp{%} respectively.
1064 @deffn Command TeX-comment-or-uncomment-region
1066 (@kbd{C-c ;}) Add or remove @samp{%} from the beginning of each line
1067 in the current region. Uncommenting works only if the region encloses
1068 solely commented lines. If @AUCTeX{} should not try to guess if the
1069 region should be commented or uncommented the commands
1070 @code{TeX-comment-region} and @code{TeX-uncomment-region} can be used
1071 to explicitly comment or uncomment the region in concern.
1074 @deffn Command TeX-comment-or-uncomment-paragraph
1076 (@kbd{C-c %}) Add or remove @samp{%} from the beginning of each line
1077 in the current paragraph. When removing @samp{%} characters the
1078 paragraph is considered to consist of all preceding and succeeding
1079 lines starting with a @samp{%}, until the first non-comment line.
1087 @cindex Reformatting
1090 Indentation means the addition of whitespace at the beginning of lines
1091 to reflect special syntactical constructs. This makes it easier to see
1092 the structure of the document, and to catch errors such as a missing
1093 closing brace. Thus, the indentation is done for precisely the same
1094 reasons that you would indent ordinary computer programs.
1096 Indentation is done by @LaTeX{} environments and by @TeX{} groups, that
1097 is the body of an environment is indented by the value of
1098 @code{LaTeX-indent-level} (default 2). Also, items of an `itemize-like'
1099 environment are indented by the value of @code{LaTeX-item-indent},
1100 default @minus{}2. (Items are identified with the help of
1101 @code{LaTeX-item-regexp}.) If more environments are nested, they are
1102 indented `accumulated' just like most programming languages usually are
1103 seen indented in nested constructs.
1104 @vindex LaTeX-indent-level
1105 @vindex LaTeX-item-indent
1106 @vindex LaTeX-item-regexp
1108 You can explicitely indent single lines, usually by pressing @key{TAB},
1109 or marked regions by calling @code{indent-region} on it. If you have
1110 @code{auto-fill-mode} enabled and a line is broken while you type it,
1111 Emacs automatically cares about the indentation in the following line.
1112 If you want to have a similar behavior upon typing @key{RET}, you can
1113 customize the variable @code{TeX-newline-function} and change the
1114 default of @code{newline} which does no indentation to
1115 @code{newline-and-indent} which indents the new line or
1116 @code{reindent-then-newline-and-indent} which indents both the current
1118 @vindex TeX-newline-function
1120 There are certain @LaTeX{} environments which should be indented in a
1121 special way, like @samp{tabular} or @samp{verbatim}. Those environments
1122 may be specified in the variable @code{LaTeX-indent-environment-list}
1123 together with their special indentation functions. Taking the
1124 @samp{verbatim} environment as an example you can see that
1125 @code{current-indentation} is used as the indentation function. This
1126 will stop @AUCTeX{} from doing any indentation in the environment if you
1127 hit @key{TAB} for example.
1128 @vindex LaTeX-indent-environment-list
1130 There are environments in @code{LaTeX-indent-environment-list} which do
1131 not bring a special indentation function with them. This is due to the
1132 fact that first the respective functions are not implemented yet and
1133 second that filling will be disabled for the specified environments.
1134 This shall prevent the source code from being messed up by accidently
1135 filling those environments with the standard filling routine. If you
1136 think that providing special filling routines for such environments
1137 would be an appropriate and challenging task for you, you are invited to
1138 contribute. (@xref{Filling}, for further information about the filling
1140 @vindex LaTeX-indent-environment-list
1142 The check for the indentation function may be enabled or disabled by
1143 customizing the variable @code{LaTeX-indent-environment-check}.
1144 @vindex LaTeX-indent-environment-check
1146 As a side note with regard to formatting special environments: Newer
1147 Emacsen include @file{align.el} and therefore provide some support for
1148 formatting @samp{tabular} and @samp{tabbing} environments with the
1149 function @code{align-current} which will nicely align columns in the
1152 @AUCTeX{} is able to format commented parts of your code just as any
1153 other part. This means @LaTeX{} environments and @TeX{} groups in
1154 comments will be indented syntactically correct if the variable
1155 @code{LaTeX-syntactic-comments} is set to t. If you disable it,
1156 comments will be filled like normal text and no syntactic indentation
1158 @vindex LaTeX-syntactic-comments
1160 Following you will find a list of most commands and variables related
1161 to indenting with a small summary in each case:
1166 @findex LaTeX-indent-line
1167 @code{LaTeX-indent-line} will indent the current line.
1171 @code{newline-and-indent} inserts a new line (much like @key{RET}) and
1172 moves the cursor to an appropriate position by the left margin.
1174 Most keyboards nowadays lack a linefeed key and @kbd{C-j} may be tedious
1175 to type. Therefore you can customize @AUCTeX{} to perform indentation
1176 upon typing @key{RET} as well. The respective option is called
1177 @code{TeX-newline-function}.
1184 @defopt LaTeX-indent-environment-list
1185 List of environments with special indentation. The second element in
1186 each entry is the function to calculate the indentation level in
1189 The filling code currently cannot handle tabular-like environments
1190 which will be completely messed-up if you try to format them. This is
1191 why most of these environments are included in this customization
1192 option without a special indentation function. This will prevent that
1196 @defopt LaTeX-indent-level
1197 Number of spaces to add to the indentation for each @samp{\begin} not
1198 matched by a @samp{\end}.
1201 @defopt LaTeX-item-indent
1202 Number of spaces to add to the indentation for @samp{\item}'s in list
1206 @defopt TeX-brace-indent-level
1207 Number of spaces to add to the indentation for each @samp{@{} not
1208 matched by a @samp{@}}.
1211 @defopt LaTeX-syntactic-comments
1212 If non-nil comments will be filled and indented according to @LaTeX{}
1213 syntax. Otherwise they will be filled like normal text.
1216 @defopt TeX-newline-function
1217 Used to specify the function which is called when @key{RET} is pressed.
1218 This will normally be @code{newline} which simply inserts a new line.
1219 In case you want to have @AUCTeX{} do indentation as well when you press
1220 @key{RET}, use the built-in functions @code{newline-and-indent} or
1221 @code{reindent-then-newline-and-indent}. The former inserts a new line
1222 and indents the following line, i.e. it moves the cursor to the right
1223 position and therefore acts as if you pressed @key{LFD}. The latter
1224 function additionally indents the current line. If you choose
1225 @samp{Other}, you can specify your own fancy function to be called when
1226 @key{RET} is pressed.
1234 @cindex Reformatting
1237 Filling deals with the insertion of line breaks to prevent lines from
1238 becoming wider than what is specified in @code{fill-column}. The
1239 linebreaks will be inserted automatically if @code{auto-fill-mode} is
1240 enabled. In this case the source is not only filled but also indented
1241 automatically as you write it.
1243 @code{auto-fill-mode} can be enabled for @AUCTeX{} by calling
1244 @code{turn-on-auto-fill} in one of the hooks @AUCTeX{} is running.
1245 @xref{Modes and Hooks}. As an example, if you want to enable
1246 @code{auto-fill-mode} in @code{LaTeX-mode}, put the following into your
1250 (add-hook 'LaTeX-mode-hook 'turn-on-auto-fill)
1253 You can manually fill explicitely marked regions, paragraphs,
1254 environments, complete sections, or the whole buffer. (Note that manual
1255 filling in @AUCTeX{} will indent the start of the region to be filled in
1256 contrast to many other Emacs modes.)
1258 There are some syntactical constructs which are handled specially with
1259 regard to filling. These are so-called code comments and paragraph
1262 Code comments are comments preceded by code or text in the same line.
1263 Upon filling a region, code comments themselves will not get filled.
1264 Filling is done from the start of the region to the line with the code
1265 comment and continues after it. In order to prevent overfull lines in
1266 the source code, a linebreak will be inserted before the last
1267 non-comment word by default. This can be changed by customizing
1268 @code{LaTeX-fill-break-before-code-comments}. If you have overfull
1269 lines with code comments you can fill those explicitely by calling
1270 @code{LaTeX-fill-paragraph} or pressing @kbd{M-q} with the cursor
1271 positioned on them. This will add linebreaks in the comment and indent
1272 subsequent comment lines to the column of the comment in the first line
1273 of the code comment. In this special case @kbd{M-q} only acts on the
1274 current line and not on the whole paragraph.
1276 Lines with @samp{\par} are treated similarly to code comments,
1277 i.e. @samp{\par} will be treated as paragraph boundary which should not
1278 be followed by other code or text. But it is not treated as a real
1279 paragraph boundary like an empty line where filling a paragraph would
1282 Paragraph commands like @samp{\section} or @samp{\noindent} (the list of
1283 commands is defined by @code{LaTeX-paragraph-commands}) are often to be
1284 placed in their own line(s). This means they should not be consecuted
1285 with any preceding or following adjacent lines of text. @AUCTeX{} will
1286 prevent this from happening if you do not put any text except another
1287 macro after the end of the last brace of the respective macro. If
1288 there is other text after the macro, @AUCTeX{} regards this as a sign
1289 that the macro is part of the following paragraph.
1290 @vindex LaTeX-paragraph-commands
1292 Here are some examples:
1300 \begin@{quote@}\label@{foo@}
1304 If you press @kbd{M-q} on the first line in both examples, nothing will
1305 change. But if you write
1308 \begin@{quote@} text
1312 and press @kbd{M-q}, you will get
1315 \begin@{quote@} text text text text text
1318 Besides code comments and paragraph commands, another speciality of
1319 filling in @AUCTeX{} involves commented lines. You should be aware that
1320 these comments are treated as islands in the rest of the @LaTeX{} code
1321 if syntactic filling is enabled. This means, for example, if you try to
1322 fill an environment with @code{LaTeX-fill-environment} and have the
1323 cursor placed on a commented line which does not have a surrounding
1324 environment inside the comment, @AUCTeX{} will report an error.
1325 @findex LaTeX-fill-environment
1327 The relevant commands and variables with regard to filling are:
1332 @findex LaTeX-fill-paragraph
1333 @code{LaTeX-fill-paragraph} will fill and indent the current paragraph.
1337 Alias for @kbd{C-c C-q C-p}
1341 @findex LaTeX-fill-environment
1342 @code{LaTeX-fill-environment} will fill and indent the current
1343 environment. This may e.g. be the `document' environment, in which case
1344 the entire document will be formatted.
1348 @findex LaTeX-fill-section
1349 @code{LaTeX-fill-section} will fill and indent the current logical
1354 @findex LaTeX-fill-region
1355 @code{LaTeX-fill-region} will fill and indent the current region.
1358 @defopt LaTeX-fill-break-at-separators
1359 List of separators before or after which respectively linebreaks will
1360 be inserted if they do not fit into one line. The separators can be
1361 curly braces, brackets, switches for inline math (@samp{$}, @samp{\(},
1362 @samp{\)}) and switches for display math (@samp{\[}, @samp{\]}). Such
1363 formatting can be useful to make macros and math more visible or to
1364 prevent overfull lines in the @LaTeX{} source in case a package for
1365 displaying formatted @TeX{} output inside the Emacs buffer, like
1366 preview-latex, is used.
1369 @defopt LaTeX-fill-break-before-code-comments
1370 Code comments are comments preceded by some other text in the same line.
1371 When a paragraph containing such a comment is to be filled, the comment
1372 start will be seen as a border after which no line breaks will be
1373 inserted in the same line. If the option
1374 @code{LaTeX-fill-break-before-code-comments} is enabled (which is the
1375 default) and the comment does not fit into the line, a line break will
1376 be inserted before the last non-comment word to minimize the chance that
1377 the line becomes overfull.
1381 @chapter Controlling Screen Display
1383 It is often desirable to get visual help of what markup code in a text
1384 actually does whithout having to decipher it explicitely. For this
1385 purpose Emacs and @AUCTeX{} provide font locking (also known as syntax
1386 highlighting) which visually sets off markup code like macros or
1387 environments by using different colors or fonts. For example text to be
1388 typeset in italics can be displayed with an italic font in the editor as
1389 well, or labels and references get their own distinct color.
1391 While font locking helps you grasp the purpose of markup code and
1392 separate markup from content, the markup code can still be distracting.
1393 @AUCTeX{} lets you hide those parts and show them again at request with
1394 its built-in support for hiding macros and environments which we call
1397 Besides folding of macros and environments, @AUCTeX{} provides support
1398 for Emacs' outline mode which lets you narrow the buffer content to
1399 certain sections of your text by hiding the parts not belonging to these
1403 * Font Locking:: Font Locking
1404 * Folding:: Folding Macros and Environments
1405 * Outline:: Outlining the Document
1409 @section Font Locking
1410 @cindex Font Locking
1411 @cindex Syntax Highlighting
1414 Font locking is supposed to improve readability of the source code by
1415 highlighting certain keywords with different colors or fonts. It
1416 thereby lets you recognize the function of markup code to a certain
1417 extent without having to read the markup command. For general
1418 information on controlling font locking with Emacs' Font Lock mode, see
1419 @ref{Font Lock, , Font Lock Mode, emacs, GNU Emacs Manual}.
1421 @defopt TeX-install-font-lock
1422 Once font locking is enabled globally or for the major modes provided by
1423 @AUCTeX{}, the font locking patterns and functionality of @fontlatex{}
1424 are activated by default. You can switch to a different font locking
1425 scheme or disable font locking in @AUCTeX{} by customizing the variable
1426 @code{TeX-install-font-lock}.
1428 Besides @fontlatex{} @AUCTeX{} ships with a scheme which is derived
1429 from Emacs' default @LaTeX{} mode and activated by choosing
1430 @code{tex-font-setup}. Be aware that this scheme is not coupled with
1431 @AUCTeX{}'s style system and not the focus of development. Therefore
1432 and due to @fontlatex{} being much more feature-rich the following
1433 explanations will only cover @fontlatex{}.
1435 In case you want to hook in your own fontification scheme, you can
1436 choose @code{other} and insert the name of the function which sets up
1437 your font locking patterns. If you want to disable fontification in
1438 @AUCTeX{} completely, choose @code{ignore}.
1441 @fontlatex{} provides many options for customization which are
1442 accessible with @kbd{M-x customize-group RET font-latex RET}. For this
1443 description the various options are explained in conceptional groups.
1446 * Fontification of macros:: Fontification of macros
1447 * Fontification of quotes:: Fontification of quotes
1448 * Fontification of math:: Fontification of math constructs
1449 * Verbatim content:: Verbatim macros and environments
1450 * Faces:: Faces used by font-latex
1451 * Known problems:: Known fontification problems
1454 @node Fontification of macros
1455 @subsection Fontification of macros
1457 Highlighting of macros can be customized by adapting keyword lists which
1458 can be found in the customization group @code{font-latex-keywords}.
1460 Three types of macros can be handled differently with respect to
1465 Commands of the form @samp{\foo[bar]@{baz@}} which consist of the macro
1466 itself, optional arguments in square brackets and mandatory arguments in
1467 curly braces. For the command itself the face
1468 @code{font-lock-keyword-face} will be used and for the optional
1469 arguments the face @code{font-lock-variable-name-face}. The face
1470 applied to the mandatory argument depends on the macro class represented
1471 by the respective built-in variables.
1473 Declaration macros of the form @samp{@{\foo text@}} which consist of the
1474 macro which may be enclosed in a @TeX{} group together with text to be
1475 affected by the macro. In case a @TeX{} group is present, the macro
1476 will get the face @code{font-lock-keyword-face} and the text will get
1477 the face configured for the respective macro class. If no @TeX{} group
1478 is present, the latter face will be applied to the macro itself.
1480 Simple macros of the form @samp{\foo} which do not have any arguments or
1481 groupings. The respective face will be applied to the macro itself.
1484 Customization variables for @samp{\foo[bar]@{baz@}} type macros allow
1485 both the macro name and the sequence of arguments to be specified. The
1486 latter is done with a string which can contain the characters
1489 indicating the existence of a starred variant for the macro,
1491 for optional arguments in brackets,
1493 for mandatory arguments in braces,
1495 for mandatory arguments consisting of a single macro and
1497 as a prefix indicating that two alternatives are following.
1499 For example the specifier for @samp{\documentclass} would be @samp{[@{}
1500 because the macro has one optional followed by one mandatory argument.
1501 The specifier for @samp{\newcommand} would be @samp{*|@{\[[@{} because
1502 there is a starred variant, the mandatory argument following the macro
1503 name can be a macro or a @TeX{} group which can be followed by two
1504 optional arguments and the last token is a mandatory argument in braces.
1506 Customization variables for the @samp{@{\foo text@}} and @samp{\foo}
1507 types are simple lists of strings where each entry is a macro name
1508 (without the leading backslash).
1510 @subheading General macro classes
1512 @fontlatex{} provides keyword lists for different macro classes which
1513 are described in the following table:
1515 @vindex font-latex-match-function-keywords
1516 @vindex font-latex-match-reference-keywords
1517 @vindex font-latex-match-textual-keywords
1518 @vindex font-latex-match-variable-keywords
1519 @vindex font-latex-match-warning-keywords
1521 @item font-latex-match-function-keywords
1522 Keywords for macros defining or related to functions, like
1523 @samp{\newcommand}.@*
1524 Type: @samp{\macro[...]@{...@}}@*
1525 Face: @code{font-lock-function-name-face}
1527 @item font-latex-match-reference-keywords
1528 Keywords for macros defining or related to references, like
1530 Type: @samp{\macro[...]@{...@}}@*
1531 Face: @code{font-lock-constant-face}
1533 @item font-latex-match-textual-keywords
1534 Keywords for macros specifying textual content, like @samp{\caption}.@*
1535 Type: @samp{\macro[...]@{...@}}@*
1536 Face: @code{font-lock-type-face}
1538 @item font-latex-match-variable-keywords
1539 Keywords for macros defining or related to variables, like
1540 @samp{\setlength}.@*
1541 Type: @samp{\macro[...]@{...@}}@*
1542 Face: @code{font-lock-variable-name-face}
1544 @item font-latex-match-warning-keywords
1545 Keywords for important macros, e.g. affecting line or page break, like
1546 @samp{\clearpage}.@*
1547 Type: @samp{\macro}@*
1548 Face: @code{font-latex-warning-face}
1551 @subheading Sectioning commands
1552 @cindex Sectioning commands, fontification of
1554 Sectioning commands are macros like @samp{\chapter} or @samp{\section}.
1555 For these commands there are two fontification schemes which may be
1556 selected by customizing the variable @code{font-latex-fontify-sectioning}.
1558 @defopt font-latex-fontify-sectioning
1559 @c Is @vindex correct?
1560 @vindex font-latex-sectioning-0-face
1561 @vindex font-latex-sectioning-1-face
1562 @vindex font-latex-sectioning-2-face
1563 @vindex font-latex-sectioning-3-face
1564 @vindex font-latex-sectioning-4-face
1565 @vindex font-latex-sectioning-5-face
1566 Per default sectioning commands will be shown in a larger, proportional
1567 font, which corresponds to a number for this variable. The font size
1568 varies with the sectioning level, e.g. @samp{\part}
1569 (@code{font-latex-sectioning-0-face}) has a larger font than
1570 @samp{\paragraph} (@code{font-latex-sectioning-5-face}). Typically,
1571 values from 1.05 to 1.3 for @code{font-latex-fontify-sectioning} give
1572 best results, depending on your font setup. If you rather like to use
1573 the base font and a different color, set the variable to the symbol
1574 @samp{color}. In this case the face @code{font-lock-type-face} will be
1575 used to fontify the argument of the sectioning commands.
1578 @vindex font-latex-match-sectioning-0-keywords
1579 @vindex font-latex-match-sectioning-1-keywords
1580 @vindex font-latex-match-sectioning-2-keywords
1581 @vindex font-latex-match-sectioning-3-keywords
1582 @vindex font-latex-match-sectioning-4-keywords
1583 @vindex font-latex-match-sectioning-5-keywords
1584 You can make @fontlatex{} aware of your own sectioning commands be
1585 adding them to the keyword lists:
1586 @code{font-latex-match-sectioning-0-keywords}
1587 (@code{font-latex-sectioning-0-face}) @dots{}
1588 @code{font-latex-match-sectioning-5-keywords}
1589 (@code{font-latex-sectioning-5-face}).
1591 @vindex font-latex-slide-title-face
1592 @vindex font-latex-match-slide-title-keywords
1593 Related to sectioning there is special support for slide titles which
1594 may be fontified with the face @code{font-latex-slide-title-face}. You
1595 can add macros which should appear in this face by customizing the
1596 variable @code{font-latex-match-slide-title-keywords}.
1598 @subheading Commands for changing fonts
1600 @LaTeX{} provides various macros for changing fonts or font attributes.
1601 For example, you can select an italic font with @samp{\textit@{...@}} or
1602 bold with @samp{\textbf@{...@}}. An alternative way to specify these
1603 fonts is to use special macros in @TeX{} groups, like @samp{@{\itshape
1604 ...@}} for italics and @samp{@{\bfseries ...@}} for bold. As mentioned
1605 above, we call the former variants commands and the latter
1608 Besides the macros for changing fonts provided by @LaTeX{} there is an
1609 infinite number of other macros---either defined by yourself for logical
1610 markup or defined by macro packages---which affect the font in the
1611 typeset text. While @LaTeX{}'s built-in macros and macros of packages
1612 known by @AUCTeX{} are already handled by @fontlatex{}, different
1613 keyword lists per type style and macro type are provided for entering
1614 your own macros which are listed in the table below.
1616 @vindex font-latex-match-bold-command-keywords
1617 @vindex font-latex-match-italic-command-keywords
1618 @vindex font-latex-match-math-command-keywords
1619 @vindex font-latex-match-type-command-keywords
1620 @vindex font-latex-match-bold-declaration-keywords
1621 @vindex font-latex-match-italic-declaration-keywords
1622 @vindex font-latex-match-type-declaration-keywords
1624 @item font-latex-match-bold-command-keywords
1625 Keywords for commands specifying a bold type style.@*
1626 Face: @code{font-latex-bold-face}
1627 @item font-latex-match-italic-command-keywords
1628 Keywords for commands specifying an italic font.@*
1629 Face: @code{font-latex-italic-face}
1630 @item font-latex-match-math-command-keywords
1631 Keywords for commands specifying a math font.@*
1632 Face: @code{font-latex-math-face}
1633 @item font-latex-match-type-command-keywords
1634 Keywords for commands specifying a typewriter font.@*
1635 Face: @code{font-lock-type-face}
1636 @item font-latex-match-bold-declaration-keywords
1637 Keywords for declarations specifying a bold type style.@*
1638 Face: @code{font-latex-bold-face}
1639 @item font-latex-match-italic-declaration-keywords
1640 Keywords for declarations specifying an italic font.@*
1641 Face: @code{font-latex-italic-face}
1642 @item font-latex-match-type-declaration-keywords
1643 Keywords for declarations specifying a typewriter font.@*
1644 Face: @code{font-latex-type-face}
1647 @subheading Deactivating defaults of built-in keyword classes
1649 @vindex font-latex-deactivated-keyword-classes
1650 @fontlatex{} ships with predefined lists of keywords for the classes
1651 described above. You can disable these defaults per class by
1652 customizing the variable @code{font-latex-deactivated-keyword-classes}.
1653 This is a list of strings for keyword classes to be deactivated. Valid
1654 entries are "warning", "variable", "reference", "function" ,
1655 "sectioning-0", "sectioning-1", "sectioning-2", "sectioning-3",
1656 "sectioning-4", "sectioning-5", "textual", "bold-command",
1657 "italic-command", "math-command", "type-command", "bold-declaration",
1658 "italic-declaration", "type-declaration".
1660 You can also get rid of certain keywords only. For example if you want
1661 to remove highlighting of footnotes as references you can put the
1662 following stanza into your init file:
1665 (eval-after-load "font-latex"
1667 font-latex-match-reference-keywords-local
1668 (remove "footnote" font-latex-match-reference-keywords-local)))
1671 But note that this means fiddling with @fontlatex{}'s internals and is
1672 not guaranteed to work in future versions of @fontlatex{}.
1674 @subheading User-defined keyword classes
1676 In case the customization options explained above do not suffice for
1677 your needs, you can specify your own keyword classes by customizing the
1678 variable @code{font-latex-user-keyword-classes}.
1680 @defopt font-latex-user-keyword-classes
1681 Every keyword class consists of four parts, a name, a list of keywords,
1682 a face and a specifier for the type of macros to be highlighted.
1684 When adding new entries, you have to use unique values for the class
1685 names, i.e. they must not clash with names of the built-in keyword
1686 classes or other names given by you. Additionally the names must not
1689 The list of keywords defines which commands and declarations should be
1690 covered by the keyword class. A keyword can either be a simple command
1691 name omitting the leading backslash or a list consisting of the command
1692 name and a string specifying the sequence of arguments for the command.
1694 The face argument can either be an existing face or font specifications
1695 made by you. (The latter option is not available on XEmacs.)
1697 There are three alternatives for the type of keywords---``Command with
1698 arguments'', ``Declaration inside @TeX{} group'' and ``Command without
1699 arguments''---which correspond with the macro types explained above.
1702 @node Fontification of quotes
1703 @subsection Fontification of quotes
1704 @cindex Quotes, fontification of
1706 Text in quotation marks is displayed with the face
1707 @code{font-latex-string-face}. Besides the various forms of opening and
1708 closing double and single quotation marks, so-called guillemets (<<, >>)
1709 can be used for quoting. Because there are two styles of using
1710 them---French style: << text >>; German style: >>text<<---you can
1711 customize the variable @code{font-latex-quotes} to tell @fontlatex{}
1712 which type you are using if the correct value cannot be derived from
1713 document properties.
1715 @defopt font-latex-quotes
1716 The default value of @code{font-latex-quotes} is @samp{auto} which means
1717 that @fontlatex{} will try to derive the correct type of quotation mark
1718 matching from document properties like the language option supplied to
1719 the babel @LaTeX{} package.
1721 If the automatic detection fails for you and you mostly use one specific
1722 style you can set it to a specific language-dependent value as well.
1723 Set the value to @samp{german} if you are using >>German quotes<< and to
1724 @samp{french} if you are using << French quotes >>. @fontlatex{} will
1725 recognize the different ways these quotes can be given in your source
1726 code, i.e. (@samp{"<}, @samp{">}), (@samp{<<}, @samp{>>}) and the
1727 respective 8-bit variants.
1729 If you set @code{font-latex-quotes} to nil, quoted content will not be
1734 @node Fontification of math
1735 @subsection Fontification of mathematical constructs
1736 @cindex Math, fontification of
1737 @cindex Subscript, fontification of
1738 @cindex Superscript, fontification of
1740 @vindex font-latex-match-math-command-keywords
1741 @vindex font-latex-math-environments
1742 In @LaTeX{} mathematics can be indicated by a variety of different
1743 methods: toggles (like dollar signs), macros and environments. Math
1744 constructs known by @fontlatex{} are displayed with the face
1745 @code{font-latex-math-face}. Support for dollar signs and shorthands
1746 like @samp{\(...\)} or @samp{\[...\]} is built-in and not customizable.
1747 Support for other math macros and environments can be adapted by
1748 customizing the variables @code{font-latex-match-math-command-keywords}
1749 and @code{font-latex-math-environments} respectively.
1751 In order to make math constructs more readable, @fontlatex{} displays
1752 subscript and superscript parts in a smaller font and raised or lowered
1753 respectively. This fontification feature can be controlled with the
1754 variables @code{font-latex-fontify-script} and
1755 @code{font-latex-script-display}.
1757 @defopt font-latex-fontify-script
1758 If non-nil, fontify subscript and superscript strings.
1760 Note that this feature is not available on XEmacs, for which it is
1761 disabled per default. In GNU Emacs raising and lowering is not enabled
1762 for versions 21.3 and before due to it working not properly.
1765 @defopt font-latex-script-display
1766 Display specification for subscript and superscript content. The car is
1767 used for subscript, the cdr is used for superscript. The feature is
1768 implemented using so-called display properties. For information on what
1769 exactly to specify for the values, see @ref{Other Display Specs, , Other
1770 Display Specifications, elisp, GNU Emacs Lisp Reference Manual}.
1773 @node Verbatim content
1774 @subsection Verbatim macros and environments
1775 @cindex Verbatim, fontification of
1777 Usually it is not desirable to have content to be typeset verbatim
1778 highlighted according to @LaTeX{} syntax. Therefore this content will
1779 be fontified uniformly with the face @code{font-latex-verbatim-face}.
1781 @vindex LaTeX-verbatim-macros-with-delims
1782 @vindex LaTeX-verbatim-macros-with-braces
1783 @vindex LaTeX-verbatim-environments
1784 @fontlatex{} differentiates three different types of verbatim
1785 constructs for fontification. Macros with special characters like | as
1786 delimiters, macros with braces, and environments. Which macros and
1787 environments are recognized is controlled by the variables
1788 @code{LaTeX-verbatim-macros-with-delims},
1789 @code{LaTeX-verbatim-macros-with-braces}, and
1790 @code{LaTeX-verbatim-environments} respectively.
1793 @subsection Faces used by @fontlatex{}
1796 In case you want to change the colors and fonts used by @fontlatex{}
1797 please refer to the faces mentioned in the explanations above and use
1798 @kbd{M-x customize-face RET <face> RET}. All faces defined by
1799 @fontlatex{} are accessible through a customization group by typing
1800 @kbd{M-x customize-group RET font-latex-highlighting-faces RET}.
1802 @node Known problems
1803 @subsection Known fontification problems
1804 @cindex Dollar signs, color bleed with
1805 @cindex Math, fontification problems with
1807 In certain cases the fontification machinery fails to interpret buffer
1808 contents correctly. This can lead to color bleed, i.e. large parts of a
1809 buffer get fontified with an inappropriate face. A typical situation
1810 for this to happen is the use of a dollar sign (@samp{$}) in a verbatim
1811 macro or environment. If @fontlatex{} is not aware of the verbatim
1812 construct, it assumes the dollar sign to be a toggle for mathematics and
1813 fontifies the following buffer content with the respective face until it
1814 finds a closing dollar sign or till the end of the buffer.
1816 As a remedy you can make the verbatim construct known to @fontlatex{},
1817 @pxref{Verbatim content}. If this is not possible, you can insert a
1818 commented dollar sign (@samp{%$}) at the next suitable end of line as a
1820 @c As a last resort one can set `font-lock-keywords-only', but we should
1821 @c probably not advise users to do this.
1825 @section Folding Macros and Environments
1832 A popular complaint about markup languages like @TeX{} and @LaTeX{} is
1833 that there is too much clutter in the source text and that one cannot
1834 focus well on the content. There are macros where you are only
1835 interested in the content they are enclosing, like font specifiers where
1836 the content might already be fontified in a special way by font locking.
1837 Or macros the content of which you only want to see when actually
1838 editing it, like footnotes or citations. Similarly you might find
1839 certain environments or comments distracting when trying to concentrate
1840 on the body of your document.
1842 With @AUCTeX{}'s folding functionality you can collapse those items and
1843 replace them by a fixed string, the content of one of their arguments,
1844 or a mixture of both. If you want to make the original text visible
1845 again in order to view or edit it, move point sideways onto the
1846 placeholder (also called display string) or left-click with the mouse
1847 pointer on it. (The latter is currently only supported on Emacs.) The
1848 macro or environment will unfold automatically, stay open as long as
1849 point is inside of it and collapse again once you move point out of it.
1850 (Note that folding of environments currently does not work in every
1853 In order to use this feature, you have to activate @code{TeX-fold-mode}
1854 which will activate the auto-reveal feature and the necessary commands
1855 to hide and show macros and environments. You can activate the mode in
1856 a certain buffer by typing the command @kbd{M-x TeX-fold-mode RET} or
1857 using the keyboard shortcut @kbd{C-c C-o C-f}. If you want to use it
1858 every time you edit a @LaTeX{} document, add it to a hook:
1859 @findex TeX-fold-mode
1863 (add-hook 'LaTeX-mode-hook (lambda ()
1867 If it should be activated in all @AUCTeX{} modes, use
1868 @code{TeX-mode-hook} instead of @code{LaTeX-mode-hook}.
1870 Once the mode is active there are several commands available to hide
1871 and show macros, environments and comments:
1873 @deffn Command TeX-fold-buffer
1875 (@kbd{C-c C-o C-b}) Hide all foldable items in the current buffer
1876 according to the setting of @code{TeX-fold-type-list}.
1878 If you want to have this done automatically every time you open a file,
1879 add it to a hook and make sure the function is called after font locking
1880 is set up for the buffer. The following code should accomplish this:
1883 (add-hook 'find-file-hook 'TeX-fold-buffer t)
1886 The command can be used any time to refresh the whole buffer and fold
1887 any new macros and environments which were inserted after the last
1888 invocation of the command.
1891 @defopt TeX-fold-type-list
1892 List of symbols determining the item classes to consider for folding.
1893 This can be macros, environments and comments. Per default only macros
1894 and environments are folded.
1897 @defopt TeX-fold-force-fontify
1898 In order for all folded content to get the right faces, the whole buffer
1899 has to be fontified before folding is carried out.
1900 @code{TeX-fold-buffer} therefore will force fontification of unfontified
1901 regions. As this will prolong the time folding takes, you can prevent
1902 forced fontification by customizing the variable
1903 @code{TeX-fold-force-fontify}.
1906 @defopt TeX-fold-preserve-comments
1907 By default items found in comments will be folded. If your comments
1908 often contain unfinished code this might lead to problems. Give this
1909 variable a non-nil value and foldable items in your comments will be
1913 @deffn Command TeX-fold-region
1915 (@kbd{C-c C-o C-r}) Hide all configured macros in the marked region.
1918 @deffn Command TeX-fold-paragraph
1920 (@kbd{C-c C-o C-p}) Hide all configured macros in the paragraph
1924 @deffn Command TeX-fold-macro
1926 (@kbd{C-c C-o C-m}) Hide the macro on which point currently is located.
1927 If the name of the macro is found in @code{TeX-fold-macro-spec-list},
1928 the respective display string will be shown instead. If it is not
1929 found, the name of the macro in sqare brackets or the default string for
1930 unspecified macros (@code{TeX-fold-unspec-macro-display-string}) will be
1931 shown, depending on the value of the variable
1932 @code{TeX-fold-unspec-use-name}.
1935 @deffn Command TeX-fold-env
1937 (@kbd{C-c C-o C-e}) Hide the environment on which point currently is
1938 located. The behavior regarding the display string is analogous to
1939 @code{TeX-fold-macro} and determined by the variables
1940 @code{TeX-fold-env-spec-list} and
1941 @code{TeX-fold-unspec-env-display-string} respectively.
1944 @deffn Command TeX-fold-math
1945 Hide the math macro on which point currently is located. If the name of
1946 the macro is found in @code{TeX-fold-math-spec-list}, the respective
1947 display string will be shown instead. If it is not found, the name of
1948 the macro in sqare brackets or the default string for unspecified macros
1949 (@code{TeX-fold-unspec-macro-display-string}) will be shown, depending
1950 on the value of the variable @code{TeX-fold-unspec-use-name}.
1953 @deffn Command TeX-fold-comment
1955 (@kbd{C-c C-o C-c}) Hide the comment point is located on.
1958 @deffn Command TeX-fold-clearout-buffer
1960 (@kbd{C-c C-o b}) Permanently unfold all macros and environments in the
1964 @deffn Command TeX-fold-clearout-region
1966 (@kbd{C-c C-o r}) Permanently unfold all macros and environments in the
1970 @deffn Command TeX-fold-clearout-paragraph
1972 (@kbd{C-c C-o p}) Permanently unfold all macros and environments in the
1973 paragraph containing point.
1976 @deffn Command TeX-fold-clearout-item
1978 (@kbd{C-c C-o i}) Permanently show the macro or environment on which
1979 point currently is located. In contrast to temporarily opening the
1980 macro when point is moved sideways onto it, the macro will be
1981 permanently unfolded and will not collapse again once point is leaving
1985 @deffn Command TeX-fold-dwim
1987 (@kbd{C-c C-o C-o}) Hide or show items according to the current context.
1988 If there is folded content, unfold it. If there is a marked region,
1989 fold all configured content in this region. If there is no folded
1990 content but a macro or environment, fold it.
1993 @vindex TeX-fold-command-prefix
1994 In case you want to use a different prefix than @kbd{C-c C-o} for these
1995 commands you can customize the variable @code{TeX-fold-command-prefix}.
1996 (Note that this will not change the key binding for activating the
1999 The commands above will only take macros or environments into
2000 consideration which are specified in the variables
2001 @code{TeX-fold-macro-spec-list} or @code{TeX-fold-env-spec-list}
2004 @defopt TeX-fold-macro-spec-list
2005 List of replacement specifiers and macros to fold. The specifier can be
2006 a string, an integer or a function symbol.
2008 If you specify a string, it will be used as a display replacement for
2009 the whole macro. Numbers in braces, brackets, parens or angle brackets
2010 will be replaced by the respective macro argument. For example
2011 @samp{@{1@}} will be replaced by the first mandatory argument of the
2012 macro. One can also define alternatives within the specifier which are
2013 used if an argument is not found. Alternatives are separated by
2014 @samp{||}. They are most useful with optional arguments. As an
2015 example, the default specifier for @samp{\item} is @samp{[1]:||*} which
2016 means that if there is an optional argument, its value is shown followed
2017 by a colon. If there is no optional argument, only an asterisk is used
2018 as the display string.
2020 If you specify a number as the first element, the content of the
2021 respective mandatory argument of a @LaTeX{} macro will be used as the
2024 If the first element is a function symbol, the function will be called
2025 with all mandatory arguments of the macro and the result of the function
2026 call will be used as a replacement for the macro.
2028 The placeholder is made by copying the text from the buffer together with
2029 its properties, i.e. its face as well. If fontification has not
2030 happened when this is done (e.g. because of lazy font locking) the
2031 intended fontification will not show up. As a workaround you can leave
2032 Emacs idle a few seconds and wait for stealth font locking to finish
2033 before you fold the buffer. Or you just re-fold the buffer with
2034 @code{TeX-fold-buffer} when you notice a wrong fontification.
2037 @defopt TeX-fold-env-spec-list
2038 List of display strings or argument numbers and environments to fold.
2039 Argument numbers refer to the @samp{\begin} statement. That means if
2040 you have e.g. @samp{\begin@{tabularx@}@{\linewidth@}@{XXX@} ...
2041 \end@{tabularx@}} and specify 3 as the argument number, the resulting
2042 display string will be ``XXX''.
2045 @defopt TeX-fold-math-spec-list
2046 List of display strings and math macros to fold.
2049 @vindex LaTeX-fold-macro-spec-list
2050 @vindex LaTeX-fold-env-spec-list
2051 @vindex LaTeX-fold-math-spec-list
2052 The variables @code{TeX-fold-macro-spec-list},
2053 @code{TeX-fold-env-spec-list}, and @code{TeX-fold-math-spec-list} apply
2054 to any @AUCTeX{} mode. If you want to make settings which are only
2055 applied to @LaTeX{} mode, you can use the mode-specific variables
2056 @code{LaTeX-fold-macro-spec-list}, @code{LaTeX-fold-env-spec-list}, and
2057 @code{LaTeX-fold-math-spec-list}
2059 @defopt TeX-fold-unspec-macro-display-string
2060 Default display string for macros which are not specified in
2061 @code{TeX-fold-macro-spec-list}.
2064 @defopt TeX-fold-unspec-env-display-string
2065 Default display string for environments which are not specified in
2066 @code{TeX-fold-env-spec-list}.
2069 @defopt TeX-fold-unspec-use-name
2070 If non-nil the name of the macro or environment surrounded by square
2071 brackets is used as display string, otherwise the defaults specified in
2072 @code{TeX-fold-unspec-macro-display-string} or
2073 @code{TeX-fold-unspec-env-display-string} respectively.
2076 When you hover with the mouse pointer over folded content, its original
2077 text will be shown in a tooltip or the echo area depending on Tooltip
2078 mode being activate. In order to avoid exorbitantly big tooltips and to
2079 cater for the limited space in the echo area the content will be cropped
2080 after a certain amount of characters defined by the variable
2081 @code{TeX-fold-help-echo-max-length}.
2083 @defopt TeX-fold-help-echo-max-length
2084 Maximum length of original text displayed in a tooltip or the echo area
2085 for folded content. Set it to zero in order to disable this feature.
2090 @section Outlining the Document
2097 @AUCTeX{} supports the standard outline minor mode using
2098 @LaTeX{}/@ConTeXt{} sectioning commands as header lines. @xref{Outline
2099 Mode, , Outline Mode, emacs, GNU Emacs Manual}.
2101 You can add your own headings by setting the variable
2102 @code{TeX-outline-extra}.
2104 @defvar TeX-outline-extra
2105 List of extra @TeX{} outline levels.
2107 Each element is a list with two entries. The first entry is the regular
2108 expression matching a header, and the second is the level of the header.
2109 A @samp{^} is automatically prepended to the regular expressions in the
2110 list, so they must match text at the beginning of the line.
2112 See @code{LaTeX-section-list} or @code{ConTeXt-INTERFACE-section-list}
2113 for existing header levels.
2116 The following example add @samp{\item} and @samp{\bibliography} headers,
2117 with @samp{\bibliography} at the same outline level as @samp{\section},
2118 and @samp{\item} being below @samp{\subparagraph}.
2121 (setq TeX-outline-extra
2122 '(("[ \t]*\\\\\\(bib\\)?item\\b" 7)
2123 ("\\\\bibliography\\b" 2)))
2126 You may want to check out the unbundled @file{out-xtra} package for even
2127 better outline support. It is available from your favorite emacs lisp
2131 @chapter Starting Processors, Viewers and Other Programs
2133 The most powerful features of @AUCTeX{} may be those allowing you to run
2134 @TeX{}, @LaTeX{}, @ConTeXt{} and other external commands like Bib@TeX{}
2135 and @code{makeindex} from within Emacs, viewing and printing the
2136 results, and moreover allowing you to @emph{debug} your documents.
2138 @cindex tool bar, toolbar
2139 @vindex LaTeX-enable-toolbar
2140 @vindex plain-TeX-enable-toolbar
2141 @AUCTeX{} comes with a special tool bar for @TeX{} and @LaTeX{} which
2142 provides buttons for the most important commands. You can enable or
2143 disable it by customizing the options @code{plain-TeX-enable-toolbar}
2144 and @code{LaTeX-enable-toolbar} in the @code{TeX-tool-bar} customization
2148 * Commands:: Invoking external commands.
2149 * Viewing:: Invoking external viewers.
2150 * Debugging:: Debugging @TeX{} and @LaTeX{} output.
2151 * Checking:: Checking the document.
2152 * Control:: Controlling the processes.
2153 * Cleaning:: Cleaning intermediate and output files.
2154 * Documentation:: Documentation about macros and packages.
2158 @section Executing Commands
2160 @cindex Running @LaTeX{}
2161 @cindex Running @TeX{}
2164 @cindex Running commands
2165 @cindex Default command
2168 @cindex Setting the header
2169 @cindex Setting the trailer
2172 @cindex Setting the default command
2174 @cindex External Commands
2176 @cindex Making an index
2177 @cindex Running @code{makeindex}
2178 @cindex @code{makeindex}
2180 @cindex Bibliography
2182 @cindex Running Bib@TeX{}
2183 @cindex Making a bibliography
2185 @cindex Writing to a printer
2187 Formatting the document with @TeX{}, @LaTeX{} or @ConTeXt{}, viewing
2188 with a previewer, printing the document, running Bib@TeX{}, making an
2189 index, or checking the document with @command{lacheck} or
2190 @command{chktex} all require running an external command.
2193 * Starting a Command:: Starting a Command on a Document or Region
2194 * Selecting a Command:: Selecting and Executing a Command
2195 * Processor Options:: Options for @TeX{} Processors
2198 @node Starting a Command
2199 @subsection Starting a Command on a Document or Region
2201 There are two ways to run an external command, you can either run it on
2202 the current document with @code{TeX-command-master}, or on the current
2203 region with @code{TeX-command-region}. A special case of running @TeX{}
2204 on a region is @code{TeX-command-buffer} which differs from
2205 @code{TeX-command-master} if the current buffer is not its own master
2208 @deffn Command TeX-command-master
2210 (@kbd{C-c C-c}) Query the user for a command, and run it on the master
2211 file associated with the current buffer. The name of the master file is
2212 controlled by the variable @code{TeX-master}. The available commands are
2213 controlled by the variable @code{TeX-command-list}.
2215 @vindex TeX-command-list
2218 @deffn Command TeX-command-region
2220 (@kbd{C-c C-r}) Query the user for a command, and run it on the contents
2221 of the selected region. The region contents are written into the region
2222 file, after extracting the header and trailer from the master file. If
2223 mark is inactive (which can happen with Transient Mark mode), use the
2224 old region. See also the command @code{TeX-pin-region} about how to fix
2227 The name of the region file is controlled by the variable
2228 @code{TeX-region}. The name of the master file is controlled by the
2229 variable @code{TeX-master}. The header is all text up to the line
2230 matching the regular expression @code{TeX-header-end}. The trailer is
2231 all text from the line matching the regular expression
2232 @code{TeX-trailer-start}. The available commands are controlled by the
2233 variable @code{TeX-command-list}.
2235 @vindex TeX-header-end
2236 @vindex TeX-trailer-start
2238 @vindex TeX-command-list
2241 @deffn Command TeX-command-buffer
2243 (@kbd{C-c C-b}) Query the user for a command, and apply it to the
2244 contents of the current buffer. The buffer contents are written into
2245 the region file, after extracting the header and trailer from the master
2246 file. The command is then actually run on the region file. See above
2251 The name of the file for temporarily storing the text when formatting
2255 @defopt TeX-header-end
2256 A regular expression matching the end of the header. By default, this
2257 is @samp{\begin@{document@}} in @LaTeX{} mode and @samp{%**end of
2258 header} in @TeX{} mode.
2261 @defopt TeX-trailer-start
2262 A regular expression matching the start of the trailer. By default,
2263 this is @samp{\end@{document@}} in @LaTeX{} mode and @samp{\bye} in
2267 If you want to change the values of @code{TeX-header-end} and
2268 @code{TeX-trailer-start} you can do this for all files by setting the
2269 variables in a mode hook or per file by specifying them as file
2270 variables (@pxref{File Variables,,,emacs,The Emacs Editor}).
2272 @deffn Command TeX-pin-region
2274 (@kbd{C-c C-t C-r}) If you don't have a mode like Transient Mark mode
2275 active, where marks get disabled automatically, the region would need to
2276 get properly set before each call to @code{TeX-command-region}. If you
2277 fix the current region with @kbd{C-c C-t C-r}, then it will get used for
2278 more commands even though mark and point may change. An explicitly
2279 activated mark, however, will always define a new region when calling
2280 @code{TeX-command-region}.
2283 @AUCTeX{} will allow one process for each document, plus one process
2284 for the region file to be active at the same time. Thus, if you are
2285 editing @var{n} different documents, you can have @var{n} plus one
2286 processes running at the same time. If the last process you started was
2287 on the region, the commands described in @ref{Debugging} and
2288 @ref{Control} will work on that process, otherwise they will work on the
2289 process associated with the current document.
2291 @node Selecting a Command
2292 @subsection Selecting and Executing a Command
2294 Once you started the command selection with @kbd{C-c C-c}, @kbd{C-c C-s}
2295 or @kbd{C-c C-b} you will be prompted for the type of command.
2296 @AUCTeX{} will try to guess which command is appropriate in the given
2297 situation and propose it as default. Usually this is a processor like
2298 @samp{TeX} or @samp{LaTeX} if the document was changed or a viewer if
2299 the document was just typeset. Other commands can be selected in the
2300 minibuffer with completion support by typing @key{TAB}.
2302 @vindex TeX-command-list
2303 @vindex TeX-expand-list
2304 The available commands are defined by the variable
2305 @code{TeX-command-list}. Per default it includes commands for
2306 typesetting the document (e.g. @samp{LaTeX}), for viewing the output
2307 (@samp{View}), for printing (@samp{Print}), for generating an index
2308 (@samp{Index}) or for spell checking (@samp{Spell}) to name but a few.
2309 You can also add your own commands by adding entries to
2310 @code{TeX-command-list}. Refer to its doc string for information about
2311 its syntax. You might also want to look at @code{TeX-expand-list} to
2312 learn about the expanders you can use in @code{TeX-command-list}.
2314 Note that the default of the variable occasionally changes. Therefore
2315 it is advisable to add to the list rather than overwriting it. You can
2316 do this with a call to @code{add-to-list} in your init file. For
2317 example, if you wanted to add a command for running a program called
2318 @samp{foo} on the master or region file, you could do this with the
2322 (eval-after-load "tex"
2323 '(add-to-list 'TeX-command-list
2324 '("Foo" "foo %s" TeX-run-command t t :help "Run foo") t))
2327 As mentioned before, @AUCTeX{} will try to guess what command you want
2328 to invoke. If you want to use another command than @samp{TeX},
2329 @samp{LaTeX} or whatever processor @AUCTeX{} thinks is appropriate for
2330 the current mode, set the variable @code{TeX-command-default}. You can
2331 do this for all files by setting it in a mode hook or per file by
2332 specifying it as a file variable (@pxref{File Variables,,,emacs,The
2335 @defopt TeX-command-default
2336 The default command to run in this buffer. Must be an entry in
2337 @code{TeX-command-list}.
2340 After confirming a command to execute, @AUCTeX{} will try to save any
2341 buffers related to the document, and check if the document needs to be
2342 reformatted. If the variable @code{TeX-save-query} is non-nil,
2343 @AUCTeX{} will query before saving each file. By default @AUCTeX{} will
2344 check emacs buffers associated with files in the current directory, in
2345 one of the @code{TeX-macro-private} directories, and in the
2346 @code{TeX-macro-global} directories. You can change this by setting the
2347 variable @code{TeX-check-path}.
2349 @defopt TeX-check-path
2350 Directory path to search for dependencies.
2352 If nil, just check the current file.
2353 Used when checking if any files have changed.
2356 @node Processor Options
2357 @subsection Options for @TeX{} Processors
2359 There are some options you can customize affecting which processors are
2360 invoked or the way this is done and which output they produce as a
2361 result. These options control if @acronym{DVI} or @acronym{PDF} output
2362 should be produced, if @TeX{} should be started in interactive or
2363 nonstop mode, if source specials or a Sync@TeX{} file should be produced
2364 for making inverse and forward search possible or which @TeX{} engine
2365 should be used instead of regular @TeX{}, like PDF@TeX{}, Omega or
2368 @deffn Command TeX-PDF-mode
2370 @vindex TeX-PDF-mode
2373 This command toggles the @acronym{PDF} mode of @AUCTeX{}, a buffer-local
2374 minor mode. You can customize @code{TeX-PDF-mode} to give it a
2375 different default. The default is used when @AUCTeX{} does not have
2376 additional clue about what a document might want. This option usually
2377 results in calling either PDF@TeX{} or ordinary @TeX{}.
2380 @defopt TeX-DVI-via-PDFTeX
2381 If this is set, @acronym{DVI} will also be produced by calling
2382 PDF@TeX{}, setting @code{\pdfoutput=0}. This makes it possible to use
2383 PDF@TeX{} features like character protrusion even when producing
2384 @acronym{DVI} files. Contemporary @TeX{} distributions do this anyway,
2385 so that you need not enable the option within @AUCTeX{}.
2388 @deffn Command TeX-interactive-mode
2390 @vindex TeX-interactive-mode
2391 (@kbd{C-c C-t C-i}) This command toggles the interactive mode of
2392 @AUCTeX{}, a global minor mode. You can customize
2393 @code{TeX-interactive-mode} to give it a different default. In
2394 interactive mode, @TeX{} will pause with an error prompt when errors are
2395 encountered and wait for the user to type something.
2398 @cindex I/O correlation
2400 @cindex Source specials
2402 @deffn Command TeX-source-correlate-mode
2404 @vindex TeX-source-correlate-mode
2405 (@kbd{C-c C-t C-s}) Toggles support for forward and inverse search.
2406 Forward search refers to jumping to the place in the previewed document
2407 corresponding to where point is located in the document source and
2408 inverse search to the other way round. @xref{I/O Correlation}.
2410 You can permanently activate @code{TeX-source-correlate-mode} by
2411 customizing the variable @code{TeX-source-correlate-mode}. There is a
2412 bunch of customization options for the mode, use @kbd{M-x
2413 customize-group @key{RET} TeX-view @key{RET}} to find out more.
2415 @vindex TeX-source-correlate-method
2416 @AUCTeX{} is aware of three different means to do I/O correlation:
2417 source specials (only DVI output), the pdfsync @LaTeX{} package (only
2418 PDF output) and Sync@TeX{}. The choice between source specials and
2419 Sync@TeX{} can be controlled with the variable
2420 @code{TeX-source-correlate-method}.
2422 Should you use source specials it has to be stressed @emph{very}
2423 strongly however, that source specials can cause differences in page
2424 breaks and spacing, can seriously interfere with various packages and
2425 should thus @emph{never} be used for the final version of a document.
2426 In particular, fine-tuning the page breaks should be done with source
2427 specials switched off.
2430 @AUCTeX{} also allows you to easily select different @TeX{} engines for
2431 processing, either by using the entries in the @samp{TeXing Options}
2432 submenu below the @samp{Command} menu or by calling the function
2433 @code{TeX-engine-set}. These eventually set the variable
2434 @code{TeX-engine} which you can also modify directly.
2437 This variable allows you to choose which @TeX{} engine should be used
2438 for typesetting the document, i.e. the executables which will be used
2439 when you invoke the @samp{TeX} or @samp{LaTeX} commands. The value
2440 should be one of the symbols defined in @code{TeX-engine-alist-builtin}
2441 or @code{TeX-engine-alist}. The symbols @samp{default}, @samp{xetex},
2442 @samp{luatex} and @samp{omega} are available from the built-in list.
2445 Note that @code{TeX-engine} is buffer-local, so setting the variable
2446 directly or via the above mentioned menu or function will not take
2447 effect in other buffers. If you want to activate an engine for all
2448 @AUCTeX{} modes, set @code{TeX-engine} in your init file, e.g. by using
2449 @kbd{M-x customize-variable <RET>}. If you want to activate it for a
2450 certain @AUCTeX{} mode only, set the variable in the respective mode
2451 hook. If you want to activate it for certain files, set it through file
2452 variables (@pxref{File Variables,,,emacs,The Emacs Editor}).
2455 @vindex LaTeX-command
2456 @vindex TeX-Omega-command
2457 @vindex LaTeX-Omega-command
2458 @vindex ConTeXt-engine
2459 @vindex ConTeXt-Omega-engine
2460 @vindex TeX-engine-alist
2461 @vindex TeX-engine-alist-builtin
2462 Should you need to change the executable names related to the different
2463 engine settings, there are some variables you can tweak. Those are
2464 @code{TeX-command}, @code{LaTeX-command}, @code{TeX-Omega-command},
2465 @code{LaTeX-Omega-command}, @code{ConTeXt-engine} and
2466 @code{ConTeXt-Omega-engine}. The rest of the executables is defined
2467 directly in @code{TeX-engine-alist-builtin}. If you want to override an
2468 entry from that, add an entry to @code{TeX-engine-alist} that starts
2469 with the same symbol as that the entry in the built-in list and specify
2470 the executables you want to use instead. You can also add entries to
2471 @code{TeX-engine-alist} in order to add support for engines not covered
2474 @defopt TeX-engine-alist
2475 Alist of TeX engines and associated commands. Each entry is a list with
2476 a maximum of five elements. The first element is a symbol used to
2477 identify the engine. The second is a string describing the engine. The
2478 third is the command to be used for plain TeX. The fourth is the
2479 command to be used for LaTeX. The fifth is the command to be used for
2480 the @samp{--engine} parameter of ConTeXt's @samp{texexec} program. Each
2481 command can either be a variable or a string. An empty string or nil
2482 means there is no command available.
2485 You can customize @AUCTeX{} to show the processor output as it is
2488 @defopt TeX-show-compilation
2489 If non-nil, the output of @TeX{} compilation is shown in another window.
2493 @section Viewing the Formatted Output
2496 @cindex Starting a previewer
2498 @AUCTeX{} allows you to start external programs for previewing the
2499 formatted output of your document.
2502 * Starting Viewers:: Starting viewers
2503 * I/O Correlation:: Forward and inverse search
2506 @node Starting Viewers
2507 @subsection Starting Viewers
2509 Viewers are normally invoked by pressing @kbd{C-c C-c} once the document
2510 is formatted, which will propose the View command, or by activating the
2511 respective entry in the Command menu. Alternatively you can type
2512 @kbd{C-c C-v} which calls the function @code{TeX-view}.
2514 @deffn Command TeX-view
2516 (@kbd{C-c C-v}) Start a viewer without confirmation. The viewer is
2517 started either on a region or the master file, depending on the last
2518 command issued. This is especially useful for jumping to the location
2519 corresponding to point in the viewer when using
2520 @code{TeX-source-correlate-mode}.
2523 @AUCTeX{} will try to guess which type of viewer (@acronym{DVI},
2524 PostScript or @acronym{PDF}) has to be used and what options are to be
2525 passed over to it. This decision is based on the output files present
2526 in the working directory as well as the class and style options used in
2527 the document. For example, if there is a @acronym{DVI} file in your
2528 working directory, a @acronym{DVI} viewer will be invoked. In case of a
2529 @acronym{PDF} file it will be a @acronym{PDF} viewer. If you specified
2530 a special paper format like @samp{a5paper} or use the @samp{landscape}
2531 option, this will be passed to the viewer by the appropriate options.
2532 Especially some @acronym{DVI} viewers depend on this kind of information
2533 in order to display your document correctly. In case you are using
2534 @samp{pstricks} or @samp{psfrag} in your document, a @acronym{DVI}
2535 viewer cannot display the contents correctly and a PostScript viewer
2536 will be invoked instead.
2538 The association between the tests for the conditions mentioned above and
2539 the viewers is made in the variable @code{TeX-view-program-selection}.
2540 Therefore this variable is the starting point for customization if you
2541 want to use other viewers than the ones suggested by default.
2543 @defopt TeX-view-program-selection
2544 This is a list of predicates and viewers which is evaluated from front
2545 to back in order to find out which viewer to call under the given
2546 conditions. In the first element of each list item you can reference
2547 one or more predicates defined in @code{TeX-view-predicate-list} or
2548 @code{TeX-view-predicate-list-builtin}. In the second element you can
2549 reference a viewer defined in @code{TeX-view-program-list} or
2550 @code{TeX-view-program-list-builtin}. The viewer of the first item with
2551 a positively evaluated predicate is selected.
2554 So @code{TeX-view-program-selection} only contains references to the
2555 actual implementations of predicates and viewer commands respectively
2556 which can be found elsewhere. @AUCTeX{} comes with a set of
2557 preconfigured predicates and viewer commands which are stored in the
2558 variables @code{TeX-view-predicate-list-builtin} and
2559 @code{TeX-view-program-list-builtin} respectively. If you are not
2560 satisfied with those and want to overwrite one of them or add your own
2561 definitions, you can do so via the variables
2562 @code{TeX-view-predicate-list} and @code{TeX-view-program-list}.
2564 @defopt TeX-view-predicate-list
2565 This is a list of predicates for viewer selection and invocation. The
2566 first element of each list item is a symbol and the second element a
2567 Lisp form to be evaluated. The form should return nil if the predicate
2570 A built-in predicate from @code{TeX-view-predicate-list-builtin} can be
2571 overwritten by defining a new predicate with the same symbol.
2574 @defopt TeX-view-program-list
2575 This is a list of viewer specifications each consisting of a symbolic
2576 name and either a command line or a function to be invoked when the
2577 viewer is called. If a command line is used, parts of it can be
2578 conditionalized by prefixing them with predicates from
2579 @code{TeX-view-predicate-list} or
2580 @code{TeX-view-predicate-list-builtin}. (See the doc string for the
2581 exact format to use.) The command line can also contain placeholders as
2582 defined in @code{TeX-expand-list} which are expanded before the viewer
2585 A built-in viewer spec from @code{TeX-view-program-list-builtin} can be
2586 overwritten by defining a new viewer spec with the same name.
2589 Note that the viewer selection and invocation as described above will
2590 only work if certain default settings in @AUCTeX{} are intact. For one,
2591 the whole viewer selection machinery will only be triggered if the
2592 @samp{%V} expander in @code{TeX-expand-list} is unchanged. So if you
2593 have trouble with the viewer invocation you might check if there is an
2594 older customization of the variable in place. In addition, the use of a
2595 function in @code{TeX-view-program-list} only works if the View command
2596 in @code{TeX-command-list} makes use of the hook
2597 @code{TeX-run-discard-or-function}.
2599 Note also that the implementation described above replaces an older one
2600 which was less flexible. This old implementation works with the
2601 variables @code{TeX-output-view-style} and @code{TeX-view-style} which
2602 are used to associate file types and style options with viewers. If
2603 desired you can reactivate it by using the placeholder @samp{%vv} for
2604 the View command in @code{TeX-command-list}. Note however, that it is
2605 bound to be removed from @AUCTeX{} once the new implementation proved to
2606 be satisfactory. For the time being, find a short description of the
2607 mentioned customization options below.
2609 @defopt TeX-output-view-style
2610 List of output file extensions, style options and view options. Each
2611 item of the list consists of three elements. If the first element (a
2612 regular expression) matches the output file extension, and the second
2613 element (a regular expression) matches the name of one of the style
2614 options, any occurrence of the string @code{%V} in a command in
2615 @code{TeX-command-list} will be replaced with the third element.
2618 @defopt TeX-view-style
2619 List of style options and view options. This is the predecessor of
2620 @code{TeX-output-view-style} which does not provide the possibility to
2621 specify output file extensions. It is used as a fallback in case none
2622 of the alternatives specified in @code{TeX-output-view-style} match. In
2623 case none of the entries in @code{TeX-view-style} match either, no
2624 suggestion for a viewer is made.
2627 @node I/O Correlation
2628 @subsection Forward and Inverse Search
2629 @cindex Inverse search
2630 @cindex Forward search
2631 @cindex I/O correlation
2632 @cindex Source specials
2636 Forward and inverse search refer to the correlation between the document
2637 source in the editor and the typeset document in the viewer. Forward
2638 search allows you to jump to the place in the previewed document
2639 corresponding to a certain line in the document source and inverse
2642 @findex TeX-source-correlate-mode
2643 @AUCTeX{} supports three methods for forward and inverse search: source
2644 specials (only DVI output), the pdfsync @LaTeX{} package (only PDF
2645 output) and Sync@TeX{} (any type of output). If you want to make use of
2646 forward and inverse searching with source specials or Sync@TeX{}, switch
2647 on @code{TeX-source-correlate-mode}. @xref{Processor Options}, on how
2648 to do that. The use of the pdfsync package is detected automatically if
2649 document parsing is enabled.
2652 Forward search happens automatically upon calling the viewer, e.g. by
2653 typing @kbd{C-c C-v} (@code{TeX-view}). This will open the viewer or
2654 bring it to front and display the output page corresponding to the
2655 position of point in the source file. @AUCTeX{} will automatically pass
2656 the necessary command line options to the viewer for this to happen.
2658 @vindex TeX-source-correlate-start-server
2659 Upon opening the viewer you will be asked if you want to start a server
2660 process (Gnuserv or Emacs server) which is necessary for inverse search.
2661 This happens only if there is no server running already. You can
2662 customize the variable @code{TeX-source-correlate-start-server} to
2663 inhibit the question and always or never start the server respectively.
2665 @defopt TeX-source-correlate-start-server
2666 If @code{TeX-source-correlate-mode} is active and a viewer is invoked,
2667 the default behavior is to ask if a server process should be started.
2668 Set this variable to @code{t} if the question should be inhibited and
2669 the server should always be started. Set it to @code{nil} if the server
2670 should never be started. Inverse search will not be available in the
2674 Inverse search, i.e. jumping to the part of your document source in
2675 Emacs corresponding to a certain position in the viewer, is triggered
2676 from the viewer, typically by a mouse click. Refer to the documentation
2677 of your viewer to find out how it has to be configured and what you have
2678 to do exactly. In xdvi you normally have to use @kbd{C-down-mouse-1}.
2681 @section Catching the errors
2684 @cindex Parsing errors
2685 @cindex Parsing TeX output
2687 @cindex Parsing @LaTeX{} errors
2688 @cindex Overfull boxes
2690 @cindex Underfull boxes
2692 Once you've formatted your document you may `debug' it, i.e. browse
2693 through the errors (La)@TeX{} reported.
2695 @deffn Command TeX-next-error
2697 (@kbd{C-c `}) Go to the next error reported by @TeX{}. The view will
2698 be split in two, with the cursor placed as close as possible to the
2699 error in the top view. In the bottom view, the error message will be
2700 displayed along with some explanatory text.
2703 Normally @AUCTeX{} will only report real errors, but you may as well
2704 ask it to report `bad boxes' and warnings as well.
2706 @deffn Command TeX-toggle-debug-bad-boxes
2708 (@kbd{C-c C-t C-b}) Toggle whether @AUCTeX{} should stop at bad boxes
2709 (i.e. overfull and underfull boxes) as well as normal errors.
2712 @deffn Command TeX-toggle-debug-warnings
2714 (@kbd{C-c C-t C-w}) Toggle whether @AUCTeX{} should stop at warnings as
2715 well as normal errors.
2718 As default, @AUCTeX{} will display a special help buffer containing the
2719 error reported by @TeX{} along with the documentation. There is however
2720 an `expert' option, which allows you to display the real @TeX{} output.
2722 @defopt TeX-display-help
2723 If t @AUCTeX{} will automatically display a help text whenever an error
2724 is encountered using @code{TeX-next-error} (@kbd{C-c `}). If nil a
2725 terse information about the error is displayed in the echo area. If
2726 @code{expert} @AUCTeX{} will display the output buffer with the raw
2731 @section Checking for problems
2733 @cindex @code{lacheck}
2734 @cindex @code{chktex}
2735 @cindex Finding errors
2736 @cindex Running @code{lacheck}
2737 @cindex Running @code{chktex}
2741 Running @TeX{} or @LaTeX{} will only find regular errors in the
2742 document, not examples of bad style. Furthermore, description of the
2743 errors may often be confusing. The utility @code{lacheck} can be used
2744 to find style errors, such as forgetting to escape the space after an
2745 abbreviation or using @samp{...} instead of @samp{\ldots} and many other
2746 problems like that. You start @code{lacheck} with @kbd{C-c C-c Check
2747 @key{RET}}. The result will be a list of errors in the
2748 @samp{*compilation*} buffer. You can go through the errors with
2749 @kbd{C-x `} (@code{next-error}, @pxref{Compilation,,,emacs,The Emacs
2750 Editor}), which will move point to the location of the next error.
2752 Another newer program which can be used to find errors is @code{chktex}.
2753 It is much more configurable than @code{lacheck}, but doesn't find all
2754 the problems @code{lacheck} does, at least in its default configuration.
2755 You must install the programs before using them, and for @code{chktex}
2756 you may also need modify @code{TeX-command-list} unless you use its
2757 @code{lacheck} compatibility wrapper. You can get @code{lacheck} from
2758 @file{<URL:ftp://ftp.ctan.org/tex-archive/support/lacheck/>} or
2759 alternatively @code{chktex} from
2760 @file{<URL:ftp://ftp.ctan.org/tex-archive/support/chktex/>}.
2763 @section Controlling the output
2764 @cindex Controlling the output
2766 @cindex Redisplay output
2768 @cindex Killing a process
2769 @cindex Finding the master file
2771 @cindex Stopping a process
2772 @cindex Current file
2773 @cindex Finding the current file
2775 A number of commands are available for controlling the output of an
2776 application running under @AUCTeX{}
2778 @deffn Command TeX-kill-job
2780 (@kbd{C-c C-k}) Kill currently running external application.
2781 This may be either of @TeX{}, @LaTeX{}, previewer, Bib@TeX{}, etc.
2784 @deffn Command TeX-recenter-output-buffer
2786 (@kbd{C-c C-l}) Recenter the output buffer so that the bottom line is
2790 @deffn Command TeX-home-buffer
2792 (@kbd{C-c ^}) Go to the `master' file in the document associated with
2793 the current buffer, or if already there, to the file where the current
2794 process was started.
2798 @section Cleaning intermediate and output files
2801 @deffn Command TeX-clean
2802 @vindex plain-TeX-clean-intermediate-suffixes
2803 @vindex plain-TeX-clean-output-suffixes
2804 @vindex LaTeX-clean-intermediate-suffixes
2805 @vindex LaTeX-clean-output-suffixes
2806 @vindex docTeX-clean-intermediate-suffixes
2807 @vindex docTeX-clean-output-suffixes
2808 @vindex Texinfo-clean-intermediate-suffixes
2809 @vindex Texinfo-clean-output-suffixes
2810 @vindex ConTeXt-clean-intermediate-suffixes
2811 @vindex ConTeXt-clean-output-suffixes
2812 Remove generated intermediate files. In case a prefix argument is
2813 given, remove output files as well.
2815 Canonical access to the function is provided by the @samp{Clean} and
2816 @samp{Clean All} entries in @code{TeX-command-list}, invokable with
2817 @kbd{C-c C-c} or the Command menu.
2819 The patterns governing which files to remove can be adapted separately
2820 for each @AUCTeX{} mode by means of the variables
2821 @code{plain-TeX-clean-intermediate-suffixes},
2822 @code{plain-TeX-clean-output-suffixes},
2823 @code{LaTeX-clean-intermediate-suffixes},
2824 @code{LaTeX-clean-output-suffixes},
2825 @code{docTeX-clean-intermediate-suffixes},
2826 @code{docTeX-clean-output-suffixes},
2827 @code{Texinfo-clean-intermediate-suffixes},
2828 @code{Texinfo-clean-output-suffixes},
2829 @code{ConTeXt-clean-intermediate-suffixes} and
2830 @code{ConTeXt-clean-output-suffixes}.
2833 @defopt TeX-clean-confirm
2834 Control if deletion of intermediate and output files has to be confirmed
2835 before it is actually done. If non-nil, ask before deleting files.
2839 @section Documentation about macros and packages
2840 @cindex Documentation
2842 @deffn Command TeX-doc
2844 (@kbd{C-c ?}) Get documentation about macros, packages or @TeX{} &
2845 Co. in general. The function will prompt for the name of a command or
2846 manual, providing a list of available keywords for completion. If point
2847 is on a command or word with available documentation, this will be
2848 suggested as default.
2850 In case no documentation could be found, a prompt for querying the
2851 @samp{texdoc} program is shown, should the latter be available.
2853 The command can be invoked by the key binding mentioned above as well as
2854 the @samp{Find Documentation...} entry in the mode menu.
2858 @chapter Customization and Extension
2861 * Modes and Hooks:: Modes and Hooks
2862 * Multifile:: Multifile Documents
2863 * Parsing Files:: Automatic Parsing of @TeX{} Files
2864 * Internationalization:: Language Support
2865 * Automatic:: Automatic Customization
2866 * Style Files:: Writing Your Own Style Support
2869 @node Modes and Hooks
2870 @section Modes and Hooks
2872 @AUCTeX{} supports a wide variety of derivatives and extensions of
2873 @TeX{}. Besides plain @TeX{} those are @LaTeX{}, AMS-@TeX{},
2874 @ConTeXt{}, Texinfo and doc@TeX{}. For each of them there is a separate
2875 major mode in @AUCTeX{} and each major mode runs @code{text-mode-hook},
2876 @code{TeX-mode-hook} as well as a hook special to the mode in this
2877 order. The following table provides an overview of the respective mode
2878 functions and hooks.
2880 @multitable {Plain @TeX{}} {@code{plain-TeX-mode}} {@code{plain-TeX-mode-hook}}
2881 @headitem Type @tab Mode function @tab Hook
2882 @item Plain @TeX{} @tab @code{plain-TeX-mode} @tab @code{plain-TeX-mode-hook}
2883 @item @LaTeX{} @tab @code{LaTeX-mode} @tab @code{LaTeX-mode-hook}
2884 @item AMS-@TeX{} @tab @code{ams-tex-mode} @tab @code{AmS-TeX-mode-hook}
2885 @item @ConTeXt{} @tab @code{ConTeXt-mode} @tab @code{ConTeXt-mode-hook}
2886 @item Texinfo @tab @code{Texinfo-mode} @tab @code{Texinfo-mode-hook}
2887 @item Doc@TeX{} @tab @code{docTeX-mode} @tab @code{docTeX-mode-hook}
2890 If you need to make a customization via a hook which is only relevant
2891 for one of the modes listed above, put it into the respective mode hook,
2892 if it is relevant for any @AUCTeX{} mode, add it to @code{TeX-mode-hook}
2893 and if it is relevant for all text modes, append it to
2894 @code{text-mode-hook}.
2897 @section Multifile Documents
2898 @cindex Multifile Documents
2900 @cindex Documents with multiple files
2901 @cindex Multiple Files
2909 You may wish to spread a document over many files (as you are likely to do if
2910 there are multiple authors, or if you have not yet discovered the power
2911 of the outline commands (@pxref{Outline})). This can be done by having a
2912 ``master'' file in which you include the various files with the @TeX{}
2913 macro @samp{\input} or the @LaTeX{} macro @samp{\include}. These
2914 files may also include other files themselves. However, to format the
2915 document you must run the commands on the top level master file.
2917 When you, for example, ask @AUCTeX{} to run a command on the master file,
2918 it has no way of knowing the name of the master file. By default,
2919 it will assume that the current file is the master file. If you insert
2920 the following in your @file{.emacs} file @AUCTeX{} will use a more
2924 (setq-default TeX-master nil) ; Query for master file.
2927 If @AUCTeX{} finds the line indicating the end of the header in a master
2928 file (@code{TeX-header-end}), it can figure out for itself that this is
2929 a master file. Otherwise, it will ask for the name of the master file
2930 associated with the buffer. To avoid asking you again, @AUCTeX{} will
2931 automatically insert the name of the master file as a file variable
2932 (@pxref{File Variables,,,emacs,The Emacs Editor}). You can also insert
2933 the file variable yourself, by putting the following text at the end of
2935 @findex TeX-header-end
2938 %%% Local Variables:
2939 %%% TeX-master: "master"
2943 You should always set this variable to the name of the top level document. If
2944 you always use the same name for your top level documents, you can set
2945 @code{TeX-master} in your @file{.emacs} file.
2948 (setq-default TeX-master "master") ; All master files called "master".
2952 The master file associated with the current buffer. If the file being
2953 edited is actually included from another file, then you can tell @AUCTeX{}
2954 the name of the master file by setting this variable. If there are
2955 multiple levels of nesting, specify the top level file.
2957 If this variable is @code{nil}, @AUCTeX{} will query you for the
2960 If the variable is @code{t}, then @AUCTeX{} will assume the file is a master
2963 If the variable is @code{shared}, then @AUCTeX{} will query for the name,
2964 but will not change the file.
2967 @defopt TeX-one-master
2968 Regular expression matching ordinary @TeX{} files.
2970 You should set this variable to match the name of all files, for which
2971 it is a good idea to append a @code{TeX-master} file variable entry
2972 automatically. When @AUCTeX{} adds the name of the master file as a
2973 file variable, it does not need to ask next time you edit the file.
2975 If you dislike @AUCTeX{} automatically modifying your files, you can
2976 set this variable to @samp{"<none>"}. By default, @AUCTeX{} will modify
2977 any file with an extension of @samp{.tex}.
2980 @deffn Command TeX-master-file-ask
2982 (@kbd{C-c _}) Query for the name of a master file and add the respective
2983 File Variables (@pxref{File Variables,,,emacs,The Emacs Editor}) to the
2984 file for setting this variable permanently.
2986 @AUCTeX{} will not ask for a master file when it encounters existing
2987 files. This function shall give you the possibility to insert the
2991 @AUCTeX{} keeps track of macros, environments, labels, and style
2992 files that are used in a given document. For this to work with
2993 multifile documents, @AUCTeX{} has to have a place to put the
2994 information about the files in the document. This is done by having an
2995 @file{auto} subdirectory placed in the directory where your document is
2996 located. Each time you save a file, @AUCTeX{} will write information
2997 about the file into the @file{auto} directory. When you load a file,
2998 @AUCTeX{} will read the information in the @file{auto} directory
2999 about the file you loaded @emph{and the master file specified by
3000 @code{TeX-master}}. Since the master file (perhaps indirectly) includes
3001 all other files in the document, @AUCTeX{} will get information from
3002 all files in the document. This means that you will get from each file,
3003 for example, completion for all labels defined anywhere in the document.
3005 @AUCTeX{} will create the @file{auto} directory automatically if
3006 @code{TeX-auto-save} is non-nil. Without it, the files in the document
3007 will not know anything about each other, except for the name of the
3008 master file. @xref{Automatic Local}.
3010 @deffn Command TeX-save-document
3012 (@kbd{C-c C-d}) Save all buffers known to belong to the current document.
3015 @defopt TeX-save-query
3016 If non-nil, then query the user before saving each file with
3017 @code{TeX-save-document}.
3022 @section Automatic Parsing of @TeX{} Files
3023 @cindex Parsing @TeX{}
3024 @cindex Automatic Parsing
3029 @AUCTeX{} depends heavily on being able to extract information from the
3030 buffers by parsing them. Since parsing the buffer can be somewhat slow,
3031 the parsing is initially disabled. You are encouraged to enable them by
3032 adding the following lines to your @file{.emacs} file.
3035 (setq TeX-parse-self t) ; Enable parse on load.
3036 (setq TeX-auto-save t) ; Enable parse on save.
3039 The latter command will make @AUCTeX{} store the parsed information in
3040 an @file{auto} subdirectory in the directory each time the @TeX{} files
3041 are stored, @pxref{Automatic Local}. If @AUCTeX{} finds the pre-parsed
3042 information when loading a file, it will not need to reparse the buffer.
3043 The information in the @file{auto} directory is also useful for
3044 multifile documents, @pxref{Multifile}, since it allows each file to
3045 access the parsed information from all the other files in the document.
3046 This is done by first reading the information from the master file, and
3047 then recursively the information from each file stored in the master
3050 The variables can also be done on a per file basis, by changing the file
3054 %%% Local Variables:
3055 %%% TeX-parse-self: t
3056 %%% TeX-auto-save: t
3060 Even when you have disabled the automatic parsing, you can force the
3061 generation of style information by pressing @kbd{C-c C-n}. This is
3062 often the best choice, as you will be able to decide when it is
3063 necessary to reparse the file.
3065 @defopt TeX-parse-self
3066 Parse file after loading it if no style hook is found for it.
3069 @defopt TeX-auto-save
3070 Automatically save style information when saving the buffer.
3073 @deffn Command TeX-normal-mode @var{arg}
3075 (@kbd{C-c C-n}) Remove all information about this buffer, and apply the
3076 style hooks again. Save buffer first including style information. With
3077 optional argument, also reload the style hooks.
3080 When @AUCTeX{} saves your buffer, it can optionally convert all tabs in
3081 your buffer into spaces.
3082 Tabs confuse @AUCTeX{}'s error message parsing and so should generally be
3083 avoided. However, tabs are significant in some environments, and so by
3084 default @AUCTeX{} does not remove them.
3085 To convert tabs to spaces when saving a buffer, insert the
3086 following in your @file{.emacs} file:
3089 (setq TeX-auto-untabify t)
3092 @defopt TeX-auto-untabify
3093 Automatically remove all tabs from a file before saving it.
3096 Instead of disabling the parsing entirely, you can also speed it
3097 significantly up by limiting the information it will search for (and
3098 store) when parsing the buffer. You can do this by setting the default
3099 values for the buffer local variables @code{TeX-auto-regexp-list} and
3100 @code{TeX-auto-parse-length} in your @file{.emacs} file.
3103 ;; Only parse LaTeX class and package information.
3104 (setq-default TeX-auto-regexp-list 'LaTeX-auto-minimal-regexp-list)
3105 ;; The class and package information is usually near the beginning.
3106 (setq-default TeX-auto-parse-length 2000)
3109 This example will speed the parsing up significantly, but @AUCTeX{}
3110 will no longer be able to provide completion for labels, macros,
3111 environments, or bibitems specified in the document, nor will it know
3112 what files belong to the document.
3114 These variables can also be specified on a per file basis, by changing
3115 the file local variables.
3118 %%% Local Variables:
3119 %%% TeX-auto-regexp-list: TeX-auto-full-regexp-list
3120 %%% TeX-auto-parse-length: 999999
3124 @defopt TeX-auto-regexp-list
3125 List of regular expressions used for parsing the current file.
3128 @defopt TeX-auto-parse-length
3129 Maximal length of @TeX{} file that will be parsed.
3132 The pre-specified lists of regexps are defined below. You can use these
3133 before loading @AUCTeX{} by quoting them, as in the example above.
3135 @defvr Constant TeX-auto-empty-regexp-list
3139 @defvr Constant LaTeX-auto-minimal-regexp-list
3140 Only parse @LaTeX{} class and packages.
3143 @defvr Constant LaTeX-auto-label-regexp-list
3144 Only parse @LaTeX{} labels.
3147 @defvr Constant LaTeX-auto-regexp-list
3148 Parse common @LaTeX{} commands.
3151 @defvr Constant plain-TeX-auto-regexp-list
3152 Parse common plain @TeX{} commands.
3155 @defvr Constant TeX-auto-full-regexp-list
3156 Parse all @TeX{} and @LaTeX{} commands that @AUCTeX{} can use.
3159 @node Internationalization
3160 @section Language Support
3161 @cindex Internationalization
3162 @cindex Language Support
3163 @cindex Character set
3164 @cindex National letters
3165 @cindex CJK language
3170 @cindex ASCII p@TeX{}
3175 @cindex CJK-@LaTeX{}
3179 @TeX{} and Emacs are usable for European (Latin, Cyrillic, Greek) based
3180 languages. Some @LaTeX{} and EmacsLisp packages are available for easy
3181 typesetting and editing documents in European languages.
3183 @c Some Texinfo macros are not used because they require quite recent
3184 @c texinfo versions (2005-03-05):
3185 @c Second arg of @acronym is available with 4.7, @comma is available in
3186 @c 4.7, @abbr is available in 4.8.
3187 @c -> @abbr{MULE, MULtilingual Enhancement to GNU Emacs}
3188 @c -> @acronym{CJK, Chinese@comma{} Japanese@comma{} and Korean}
3190 For @acronym{CJK} (Chinese, Japanese, and Korean) languages, Emacs or
3191 XEmacs with @acronym{MULE} (MULtilingual Enhancement to GNU Emacs)
3192 support is required. @acronym{MULE} is part of Emacs by default since
3193 Emacs 20. XEmacs has to be configured with the @samp{--with-mule}
3194 option. Special versions of @TeX{} are needed for @acronym{CJK}
3195 languages: C@TeX{} and China@TeX{} for Chinese, ASCII p@TeX{} and NTT
3196 j@TeX{} for Japanese, H@LaTeX{} and k@TeX{} for Korean. The
3197 @acronym{CJK}-@LaTeX{} package is required for supporting multiple
3198 @acronym{CJK} scripts within a single document.
3200 Note that Unicode is not fully supported in Emacs 21 and XEmacs 21.
3201 @acronym{CJK} characters are not usable. Please use the
3202 @acronym{MULE}-@acronym{UCS} EmacsLisp package or Emacs 22 (not released
3203 yet) if you need @acronym{CJK}.
3205 @c FIXME: We need more information for CTeX, ChinaTeX, KTeX, and HLaTeX.
3208 * European:: Using @AUCTeX{} with European Languages
3209 * Japanese:: Using @AUCTeX{} with Japanese
3213 @subsection Using @AUCTeX{} with European Languages
3215 @cindex European Characters
3216 @cindex ISO 8859 Latin 1
3218 @cindex ISO 8859 Latin 2
3222 @subsubsection Typing and Displaying Non-ASCII Characters
3224 First you will need a way to write non-ASCII characters. You can either
3225 use macros, or teach @TeX{} about the ISO character sets. I prefer the
3226 latter, it has the advantage that the usual standard emacs word
3227 movement and case change commands will work.
3229 With @LaTeX{}2e, just add @samp{\usepackage[latin1]@{inputenc@}}. Other
3230 languages than Western European ones will probably have other encoding
3233 To be able to display non-ASCII characters you will need an appropriate
3234 font and a version of GNU Emacs capable of displaying 8-bit characters
3235 (e.g. Emacs 21). The manner in which this is supported differs between
3236 Emacsen, so you need to take a look at your respective documentation.
3238 A compromise is to use an European character set when editing the file,
3239 and convert to @TeX{} macros when reading and writing the files.
3243 @cindex @file{iso-cvt.el}
3244 Much like @file{iso-tex.el} but is bundled with Emacs 19.23 and later.
3247 @cindex @file{x-compose.el}
3248 Similar package bundled with new versions of XEmacs.
3252 a much more complete package for both Emacs and XEmacs that can also
3253 handle a lot of mathematical characters and input methods.
3256 @subsubsection Style Files for Different Languages
3259 @AUCTeX{} supports style files for several languages. Each style file
3260 may modify @AUCTeX{} to better support the language, and will run
3261 a language specific hook that will allow you to for example change
3262 ispell dictionary, or run code to change the keyboard remapping. The
3263 following will for example choose a Danish dictionary for documents
3264 including @samp{\usepackage[danish]@{babel@}}.
3265 This requires parsing to be enabled, @pxref{Parsing Files}.
3268 (add-hook 'TeX-language-dk-hook
3269 (lambda () (ispell-change-dictionary "danish")))
3272 The following style files are recognized:
3274 @c In alphabetic order of the hooks:
3275 @vindex TeX-language-bg-hook
3276 @vindex TeX-language-cz-hook
3277 @vindex TeX-language-dk-hook
3278 @vindex TeX-language-nl-hook
3279 @vindex TeX-language-de-hook
3280 @vindex TeX-language-it-hook
3281 @vindex TeX-language-is-hook
3282 @vindex TeX-language-pl-hook
3283 @vindex TeX-language-sk-hook
3284 @vindex TeX-language-sv-hook
3296 Runs style hook @code{TeX-language-bg-hook}. Gives @samp{"} word
3297 syntax, makes the @key{"} key insert a literal @samp{"}. Typing @key{"}
3298 twice will insert insert @samp{"`} or @samp{"'} depending on context.
3299 Typing @key{-} twice will insert @samp{"=}, three times @samp{--}.
3302 Runs style hook @code{TeX-language-cz-hook}. Pressing @key{"} will
3303 insert @samp{\uv@{} and @samp{@}} depending on context.
3305 @c Is the difference between dk and danish really intented?
3307 Runs style hook @code{TeX-language-dk-hook}. Pressing @key{"} will
3308 insert @samp{"`} and @samp{"'} depending on context. Typing @key{-}
3309 twice will insert @samp{"=}, i.e. a hyphen string allowing hyphenation
3310 in the composing words.
3311 @c dk.sty seems to be obsolete, so we don't want to encourage using it.
3313 @c Runs style hook @code{TeX-language-dk-hook}.
3316 Runs style hook @code{TeX-language-nl-hook}.
3320 Runs style hook @code{TeX-language-de-hook}. Gives @samp{"} word
3321 syntax, makes the @key{"} key insert a literal @samp{"}. Pressing the
3322 key twice will give you opening or closing German quotes (@samp{"`} or
3323 @samp{"'}). Typing @key{-} twice will insert @samp{"=}, three times
3328 Runs style hook @code{TeX-language-fr-hook}. Pressing @key{"} will
3329 insert @samp{\\og} and @samp{\\fg} depending on context. Note that the
3330 language name for customizing @code{TeX-quote-language-alist} is
3334 Runs style hook @code{TeX-language-is-hook}. Gives @samp{"} word
3335 syntax, makes the @key{"} key insert a literal @samp{"}. Typing @key{"}
3336 twice will insert insert @samp{"`} or @samp{"'} depending on context.
3337 Typing @key{-} twice will insert @samp{"=}, three times @samp{--}.
3340 Runs style hook @code{TeX-language-it-hook}. Pressing @key{"} will
3341 insert @samp{"<} and @samp{">} depending on context.
3344 Runs style hook @code{TeX-language-pl-hook}. Gives @samp{"} word syntax
3345 and makes the @key{"} key insert a literal @samp{"}. Pressing @key{"}
3346 twice will insert @samp{"`} or @samp{"'} depending on context.
3349 Runs style hook @code{TeX-language-pl-hook}. Makes the @key{"} key
3350 insert a literal @samp{"}. Pressing @key{"} twice will insert @samp{,,}
3351 or @samp{''} depending on context.
3354 Runs style hook @code{TeX-language-sk-hook}. Pressing @key{"} will
3355 insert @samp{\uv@{} and @samp{@}} depending on context.
3358 Runs style hook @code{TeX-language-sv-hook}. Pressing @key{"} will
3359 insert @samp{''}. Typing @key{-} twice will insert @samp{"=}, three
3363 Replacement of language-specific hyphen strings like @samp{"=} with
3364 dashes does not require to type @key{-} three times in a row. You can
3365 put point after the hypen string anytime and trigger the replacement by
3368 In case you are not satisfied with the suggested behavior of quote and
3369 hyphen insertion you can change it by customizing the variables
3370 @code{TeX-quote-language-alist} and
3371 @code{LaTeX-babel-hyphen-language-alist} respectively.
3373 @defopt TeX-quote-language-alist
3374 Used for overriding the default language-specific quote insertion
3375 behavior. This is an alist where each element is a list consisting of
3376 four items. The first item is the name of the language in concern as a
3377 string. See the list of supported languages above. The second item is
3378 the opening quotation mark. The third item is the closing quotation
3379 mark. Opening and closing quotation marks can be specified directly as
3380 strings or as functions returning a string. The fourth item is a
3381 boolean controlling quote insertion. It should be non-nil if if the
3382 special quotes should only be used after inserting a literal @samp{"}
3383 character first, i.e. on second key press.
3386 @defopt LaTeX-babel-hyphen-language-alist
3387 Used for overriding the behavior of hyphen insertion for specific
3388 languages. Every element in this alist is a list of three items. The
3389 first item should specify the affected language as a string. The second
3390 item denotes the hyphen string to be used as a string. The third item,
3391 a boolean, controls the behavior of hyphen insertion and should be
3392 non-nil if the special hyphen should be inserted after inserting a
3393 literal @samp{-} character, i.e. on second key press.
3396 The defaults of hyphen insertion are defined by the variables
3397 @code{LaTeX-babel-hyphen} and @code{LaTeX-babel-hyphen-after-hyphen}
3400 @defopt LaTeX-babel-hyphen
3401 String to be used when typing @key{-}. This usually is a hyphen
3402 alternative or hyphenation aid provided by @samp{babel} and the related
3403 language style files, like @samp{"=}, @samp{"~} or @samp{"-}.
3405 Set it to an empty string or nil in order to disable language-specific
3409 @defopt LaTeX-babel-hyphen-after-hyphen
3410 Control insertion of hyphen strings. If non-nil insert normal hyphen on
3411 first key press and swap it with the language-specific hyphen string
3412 specified in the variable @code{LaTeX-babel-hyphen} on second key press.
3413 If nil do it the other way round.
3417 @subsection Using @AUCTeX{} with Japanese @TeX{}
3425 @cindex ASCII p@TeX{}
3428 @cindex @file{tex-jp.el}
3429 @vindex TeX-default-mode
3430 @vindex japanese-TeX-command-default
3431 @vindex japanese-LaTeX-command-default
3432 @vindex japanese-LaTeX-default-style
3434 To write Japanese text with @AUCTeX{}, you need to have versions of
3435 @TeX{} and Emacs that support Japanese. There exist at least two
3436 variants of @TeX{} for Japanese text (NTT j@TeX{} and ASCII p@TeX{}).
3437 @AUCTeX{} can be used with @acronym{MULE, MULtilingual Enhancement to GNU
3438 Emacs} supported Emacsen.
3440 To use the Japanese @TeX{} variants, simply activate
3441 @code{japanese-plain-tex-mode} or @code{japanese-latex-mode} and
3442 everything should work. If not, send mail to Masayuki Ataka
3443 @samp{<ataka@@milk.freemail.ne.jp>}, who kindly donated the code for
3444 supporting Japanese in @AUCTeX{}. None of the primary @AUCTeX{}
3445 maintainers understand Japanese, so they cannot help you.
3447 If you usually use @AUCTeX{} in Japanese, setting the following
3448 variables is useful.
3450 @defopt TeX-default-mode
3451 Mode to enter for a new file when it cannott be determined whether the
3452 file is plain @TeX{} or @LaTeX{} or what.
3454 If you want to enter Japanese @LaTeX{} mode whenever this may happen,
3455 set the variable like this:
3457 (setq TeX-default-mode 'japanese-latex-mode)
3461 @defopt japanese-TeX-command-default
3462 The default command for @code{TeX-command} in Japanese @TeX{} mode.
3464 The default value is @samp{"pTeX"}.
3467 @defopt japanese-LaTeX-command-default
3468 The default command for @code{TeX-command} in Japanese @LaTeX{} mode.
3470 The default value is @samp{"LaTeX"}.
3473 @defopt japanese-LaTeX-default-style
3474 The default style/class when creating a new Japanese @LaTeX{} document.
3476 The default value is @samp{"jarticle"}.
3479 See @file{tex-jp.el} for more information.
3482 @section Automatic Customization
3483 @cindex Automatic Customization
3484 @cindex Extracting @TeX{} symbols
3486 @cindex @file{auto} directories.
3487 @cindex Parsing @TeX{}
3488 @cindex @TeX{} parsing
3489 @cindex Generating symbols
3491 Since @AUCTeX{} is so highly customizable, it makes sense that it is able
3492 to customize itself. The automatic customization consists of scanning
3493 @TeX{} files and extracting symbols, environments, and things like that.
3495 The automatic customization is done on three different levels. The
3496 global level is the level shared by all users at your site, and consists
3497 of scanning the standard @TeX{} style files, and any extra styles added
3498 locally for all users on the site. The private level deals with those
3499 style files you have written for your own use, and use in different
3500 documents. You may have a @file{~/lib/TeX/} directory where you store
3501 useful style files for your own use. The local level is for a specific
3502 directory, and deals with writing customization for the files for your
3503 normal @TeX{} documents.
3505 If compared with the environment variable @code{TEXINPUTS}, the
3506 global level corresponds to the directories built into @TeX{}. The
3507 private level corresponds to the directories you add yourself, except for
3508 @file{.}, which is the local level.
3511 * Automatic Global:: Automatic Customization for the Site
3512 * Automatic Private:: Automatic Customization for a User
3513 * Automatic Local:: Automatic Customization for a Directory
3516 By default @AUCTeX{} will search for customization files in all the
3517 global, private, and local style directories, but you can also set the
3518 path directly. This is useful if you for example want to add another
3519 person's style hooks to your path. Please note that all matching files
3520 found in @code{TeX-style-path} are loaded, and all hooks defined in the
3521 files will be executed.
3523 @defopt TeX-style-path
3524 List of directories to search for @AUCTeX{} style files.
3525 Each must end with a slash.
3528 By default, when @AUCTeX{} searches a directory for files, it will
3529 recursively search through subdirectories.
3531 @defopt TeX-file-recurse
3532 Whether to search @TeX{} directories recursively: nil means do not
3533 recurse, a positive integer means go that far deep in the directory
3534 hierarchy, t means recurse indefinitely.
3537 By default, @AUCTeX{} will ignore files name @file{.}, @file{..},
3538 @file{SCCS}, @file{RCS}, and @file{CVS}.
3540 @defopt TeX-ignore-file
3541 Regular expression matching file names to ignore.
3543 These files or directories will not be considered when searching for
3544 @TeX{} files in a directory.
3547 @node Automatic Global
3548 @subsection Automatic Customization for the Site
3549 @cindex Global style hook directory
3550 @cindex Global macro directory
3551 @cindex Site macro directory
3552 @cindex Global @TeX{} macro directory
3553 @cindex Site @TeX{} macro directory
3554 @cindex Global directories
3555 @cindex Site information
3557 Assuming that the automatic customization at the global level was done
3558 when @AUCTeX{} was installed, your choice is now: will you use it? If
3559 you use it, you will benefit by having access to all the symbols and
3560 environments available for completion purposes. The drawback is slower
3561 load time when you edit a new file and perhaps too many confusing
3562 symbols when you try to do a completion.
3564 You can disable the automatic generated global style hooks by setting
3565 the variable @code{TeX-auto-global} to nil.
3567 @defopt TeX-macro-global
3568 Directories containing the site's @TeX{} style files.
3571 @defopt TeX-style-global
3572 Directory containing hand generated @TeX{} information.
3573 Must end with a slash.
3575 These correspond to @TeX{} macros shared by all users of a site.
3578 @defopt TeX-auto-global
3579 Directory containing automatically generated information.
3581 For storing automatic extracted information about the @TeX{} macros
3582 shared by all users of a site.
3585 @node Automatic Private
3586 @subsection Automatic Customization for a User
3587 @cindex Private style hook directory
3588 @cindex Private macro directory
3589 @cindex Personal macro directory
3590 @cindex Private @TeX{} macro directory
3591 @cindex Personal @TeX{} macro directory
3592 @cindex Private directories
3593 @cindex Personal information
3595 You should specify where you store your private @TeX{} macros, so
3596 @AUCTeX{} can extract their information. The extracted information will
3597 go to the directories listed in @code{TeX-auto-private}
3599 Use @kbd{M-x TeX-auto-generate @key{RET}} to extract the information.
3601 @defopt TeX-macro-private
3602 Directories where you store your personal @TeX{} macros. The value
3603 defaults to the directories listed in the @samp{TEXINPUTS} and
3604 @samp{BIBINPUTS} environment variables or to the respective directories
3605 in @code{$TEXMFHOME} if no results can be obtained from the environment
3609 @defopt TeX-auto-private
3610 List of directories containing automatically generated @AUCTeX{} style
3611 files. These correspond to the personal @TeX{} macros.
3614 @deffn Command TeX-auto-generate @var{TEX} @var{AUTO}
3615 (@kbd{M-x TeX-auto-generate @key{RET}}) Generate style hook for
3616 @var{TEX} and store it in @var{AUTO}. If @var{TEX} is a directory,
3617 generate style hooks for all files in the directory.
3620 @defopt TeX-style-private
3621 List of directories containing hand generated @AUCTeX{} style files.
3622 These correspond to the personal @TeX{} macros.
3625 @node Automatic Local
3626 @subsection Automatic Customization for a Directory
3627 @cindex Local style hooks
3628 @cindex Updating style hooks
3629 @cindex Automatic updating style hooks
3630 @cindex Local style hooks
3631 @cindex Local style directory
3633 @AUCTeX{} can update the style information about a file each time you
3634 save it, and it will do this if the directory @code{TeX-auto-local}
3635 exist. @code{TeX-auto-local} is by default set to @samp{"auto"}, so
3636 simply creating an @file{auto} directory will enable automatic saving of
3639 The advantage of doing this is that macros, labels, etc. defined in any
3640 file in a multifile document will be known in all the files in the
3641 document. The disadvantage is that saving will be slower. To disable,
3642 set @code{TeX-auto-local} to nil.
3644 @defopt TeX-style-local
3645 Directory containing hand generated @TeX{} information.
3646 Must end with a slash.
3648 These correspond to @TeX{} macros found in the current directory.
3651 @defopt TeX-auto-local
3652 Directory containing automatically generated @TeX{} information.
3653 Must end with a slash.
3655 These correspond to @TeX{} macros found in the current directory.
3659 @section Writing Your Own Style Support
3662 @cindex @file{style}
3664 @xref{Automatic}, for a discussion about automatically generated global,
3665 private, and local style files. The hand generated style files are
3666 equivalent, except that they by default are found in @file{style}
3667 directories instead of @file{auto} directories.
3670 * Simple Style:: A Simple Style File
3671 * Adding Macros:: Adding Support for Macros
3672 * Adding Environments:: Adding Support for Environments
3673 * Adding Other:: Adding Other Information
3674 * Hacking the Parser:: Automatic Extraction of New Things
3677 If you write some useful support for a public @TeX{} style file, please
3681 @subsection A Simple Style File
3682 @cindex @file{book.el}
3683 @cindex Sample style file
3685 @cindex Example of a style file.
3687 @cindex Adding a style hook
3689 Here is a simple example of a style file.
3692 ;;; book.el - Special code for book style.
3697 (LaTeX-largest-level-set "chapter")))
3700 This file specifies that the largest kind of section in a @LaTeX{} document
3701 using the book document style is chapter. The interesting thing to
3702 notice is that the style file defines an (anonymous) function, and adds it
3703 to the list of loaded style hooks by calling @code{TeX-add-style-hook}.
3705 The first time the user indirectly tries to access some style specific
3706 information, such as the largest sectioning command available, the style
3707 hooks for all files directly or indirectly read by the current document
3708 is executed. The actual files will only be evaluated once, but the
3709 hooks will be called for each buffer using the style file.
3711 @defun TeX-add-style-hook @var{style} @var{hook}
3712 Add @var{hook} to the list of functions to run when we use the @TeX{}
3717 @subsection Adding Support for Macros
3718 @cindex Adding macros
3719 @cindex Macros, adding
3720 @cindex Defining macros in style hooks
3722 The most common thing to define in a style hook is new symbols (@TeX{}
3723 macros). Most likely along with a description of the arguments to the
3724 function, since the symbol itself can be defined automatically.
3726 Here are a few examples from @file{latex.el}.
3733 '("arabic" TeX-arg-counter)
3734 '("label" TeX-arg-define-label)
3735 '("ref" TeX-arg-label)
3736 '("newcommand" TeX-arg-define-macro [ "Number of arguments" ] t)
3737 '("newtheorem" TeX-arg-define-environment
3738 [ TeX-arg-environment "Numbered like" ]
3739 t [ TeX-arg-counter "Within counter" ]))))
3742 @defun TeX-add-symbols @var{symbol} @dots{}
3743 Add each @var{symbol} to the list of known symbols.
3746 Each argument to @code{TeX-add-symbols} is a list describing one symbol.
3747 The head of the list is the name of the symbol, the remaining elements
3748 describe each argument.
3750 If there are no additional elements, the symbol will be inserted with
3751 point inside braces. Otherwise, each argument of this function should
3752 match an argument of the @TeX{} macro. What is done depends on the argument
3755 If a macro is defined multiple times, @AUCTeX{} will chose the one with
3756 the longest definition (i.e. the one with the most arguments).
3760 '("tref" 1) ; one argument
3764 '("tref" TeX-arg-label ignore) ; two arguments
3767 @code{ignore} is a function that does not do anything, so when you
3768 insert a @samp{tref} you will be prompted for a label and no more.
3770 You can use the following types of specifiers for arguments:
3774 Use the string as a prompt to prompt for the argument.
3777 Insert that many braces, leave point inside the first.
3780 Insert empty braces.
3783 Insert empty braces, leave point between the braces.
3786 Call the symbol as a function. You can define your
3787 own hook, or use one of the predefined argument hooks.
3790 If the car is a string, insert it as a prompt and the next
3791 element as initial input. Otherwise, call the car of the list with
3792 the remaining elements as arguments.
3795 Optional argument. If it has more than one element, parse it
3796 as a list, otherwise parse the only element as above. Use square
3797 brackets instead of curly braces, and is not inserted on empty user
3801 A lot of argument hooks have already been defined. The first argument to
3802 all hooks is a flag indicating if it is an optional argument. It is up
3803 to the hook to determine what to do with the remaining arguments, if
3804 any. Typically the next argument is used to overwrite the default
3808 @item TeX-arg-conditional
3809 Implements if EXPR THEN ELSE. If EXPR evaluates to true, parse THEN as an
3810 argument list, else parse ELSE as an argument list.
3812 @item TeX-arg-literal
3813 Insert its arguments into the buffer. Used for specifying extra syntax
3817 Parse its arguments but use no braces when they are inserted.
3820 Evaluate arguments and insert the result in the buffer.
3823 Prompt for a label completing with known labels.
3826 Prompt for a @TeX{} macro with completion.
3828 @item TeX-arg-environment
3829 Prompt for a @LaTeX{} environment with completion.
3832 Prompt for a Bib@TeX{} citation.
3834 @item TeX-arg-counter
3835 Prompt for a @LaTeX{} counter.
3837 @item TeX-arg-savebox
3838 Prompt for a @LaTeX{} savebox.
3841 Prompt for a filename in the current directory, and use it without the
3844 @item TeX-arg-input-file
3845 Prompt for the name of an input file in @TeX{}'s search path, and use it
3846 without the extension. Run the style hooks for the file.
3848 @item TeX-arg-define-label
3849 Prompt for a label completing with known labels. Add label to list of
3852 @item TeX-arg-define-macro
3853 Prompt for a @TeX{} macro with completion. Add macro to list of defined
3856 @item TeX-arg-define-environment
3857 Prompt for a @LaTeX{} environment with completion. Add environment to
3858 list of defined environments.
3860 @item TeX-arg-define-cite
3861 Prompt for a Bib@TeX{} citation.
3863 @item TeX-arg-define-counter
3864 Prompt for a @LaTeX{} counter.
3866 @item TeX-arg-define-savebox
3867 Prompt for a @LaTeX{} savebox.
3869 @item TeX-arg-corner
3870 Prompt for a @LaTeX{} side or corner position with completion.
3873 Prompt for a @LaTeX{} side with completion.
3876 Prompt for a @LaTeX{} side with completion.
3878 @item TeX-arg-pagestyle
3879 Prompt for a @LaTeX{} pagestyle with completion.
3882 Prompt for delimiter and text.
3885 Insert a pair of numbers, use arguments for prompt. The numbers are
3886 surrounded by parentheses and separated with a comma.
3889 Insert width and height as a pair. No arguments.
3891 @item TeX-arg-coordinate
3892 Insert x and y coordinates as a pair. No arguments.
3895 If you add new hooks, you can assume that point is placed directly after
3896 the previous argument, or after the macro name if this is the first
3897 argument. Please leave point located after the argument you are
3898 inserting. If you want point to be located somewhere else after all
3899 hooks have been processed, set the value of @code{exit-mark}. It will
3900 point nowhere, until the argument hook sets it.
3902 @node Adding Environments
3903 @subsection Adding Support for Environments
3904 @cindex Adding environments
3905 @cindex Environments, adding
3906 @cindex Defining environments in style hooks
3908 Adding support for environments is very much like adding support for
3909 @TeX{} macros, except that each environment normally only takes one
3910 argument, an environment hook. The example is again a short version of
3917 (LaTeX-add-environments
3918 '("document" LaTeX-env-document)
3919 '("enumerate" LaTeX-env-item)
3920 '("itemize" LaTeX-env-item)
3921 '("list" LaTeX-env-list))))
3924 It is completely up to the environment hook to insert the environment,
3925 but the function @code{LaTeX-insert-environment} may be of some help.
3926 The hook will be called with the name of the environment as its first
3927 argument, and extra arguments can be provided by adding them to a list
3930 For simple environments with arguments, for example defined with
3931 @samp{\newenvironment}, you can make @AUCTeX{} prompt for the arguments
3932 by giving the prompt strings in the call to
3933 @code{LaTeX-add-environments}. The fact that an argument is optional
3934 can be indicated by wrapping the prompt string in a vector.
3936 For example, if you have defined a @code{loop} environment with the
3937 three arguments @var{from}, @var{to}, and @var{step}, you can add
3938 support for them in a style file.
3943 \newenvironment@{loop@}[3]@{...@}@{...@}
3952 (LaTeX-add-environments
3953 '("loop" "From" "To" "Step"))))
3956 If an environment is defined multiple times, @AUCTeX{} will choose the
3957 one with the longest definition. Thus, if you have an enumerate style
3958 file, and want it to replace the standard @LaTeX{} enumerate hook above,
3959 you could define an @file{enumerate.el} file as follows, and place it in
3960 the appropriate style directory.
3966 (LaTeX-add-environments
3967 '("enumerate" LaTeX-env-enumerate foo))))
3969 (defun LaTeX-env-enumerate (environment &optional ignore) ...)
3972 The symbol @code{foo} will be passed to @code{LaTeX-env-enumerate} as
3973 the second argument, but since we only added it to overwrite the
3974 definition in @file{latex.el} it is just ignored.
3976 @defun LaTeX-add-environments @var{env} @dots{}
3977 Add each @var{env} to list of loaded environments.
3980 @defun LaTeX-insert-environment @var{env} [ @var{extra} ]
3981 Insert environment of type @var{env}, with optional argument @var{extra}.
3984 Following is a list of available hooks for
3985 @code{LaTeX-add-environments}:
3988 @item LaTeX-env-item
3989 Insert the given environment and the first item.
3991 @item LaTeX-env-figure
3992 Insert the given figure-like environment with a caption and a label.
3994 @item LaTeX-env-array
3995 Insert the given array-like environment with position and column
3998 @item LaTeX-env-label
3999 Insert the given environment with a label.
4001 @item LaTeX-env-list
4002 Insert the given list-like environment, a specifier for the label and
4005 @item LaTeX-env-minipage
4006 Insert the given minipage-like environment with position and width
4009 @item LaTeX-env-tabular*
4010 Insert the given tabular*-like environment with width, position and
4011 column specifications.
4013 @item LaTeX-env-picture
4014 Insert the given environment with width and height specifications.
4017 Insert the given environment with a label for a bibitem.
4019 @item LaTeX-env-contents
4020 Insert the given environment with a filename as its argument.
4022 @item LaTeX-env-args
4023 Insert the given environment with arguments. You can use this as a hook
4024 in case you want to specify multiple complex arguments just like in
4025 elements of @code{TeX-add-symbols}. This is most useful if the
4026 specification of arguments to be prompted for with strings and strings
4027 wrapped in a vector as described above is too limited.
4029 Here is an example from @file{listings.el} which calls a function with
4030 one argument in order to prompt for a key=value list to be inserted as
4031 an optional argument of the @samp{lstlisting} environment:
4034 (LaTeX-add-environments
4035 `("lstlisting" LaTeX-env-args
4036 [TeX-arg-key-val ,LaTeX-listings-key-val-options]))
4041 @subsection Adding Other Information
4042 @cindex Adding bibliographies
4043 @cindex Bibliographies, adding
4044 @cindex Defining bibliographies in style hooks
4045 @cindex Adding labels
4046 @cindex Labels, adding
4047 @cindex Defining labels in style hooks
4048 @cindex Adding other information
4049 @cindex Other information, adding
4050 @cindex Defining other information in style hooks
4052 You can also specify bibliographical databases and labels in the style
4053 file. This is probably of little use, since this information will
4054 usually be automatically generated from the @TeX{} file anyway.
4056 @defun LaTeX-add-bibliographies @var{bibliography} @dots{}
4057 Add each @var{bibliography} to list of loaded bibliographies.
4060 @defun LaTeX-add-labels @var{label} @dots{}
4061 Add each @var{label} to the list of known labels.
4064 @node Hacking the Parser
4065 @subsection Automatic Extraction of New Things
4066 @cindex Parsing new macros
4067 @cindex @file{macro.tex}
4068 @cindex @file{macro.el}
4069 @cindex Changing the parser
4071 The automatic @TeX{} information extractor works by searching for
4072 regular expressions in the @TeX{} files, and storing the matched
4073 information. You can add support for new constructs to the parser,
4074 something that is needed when you add new commands to define symbols.
4076 For example, in the file @file{macro.tex} I define the following macro.
4079 \newcommand@{\newmacro@}[5]@{%
4080 \def#1@{#3\index@{#4@@#5~cite@{#4@}@}\nocite@{#4@}@}%
4081 \def#2@{#5\index@{#4@@#5~cite@{#4@}@}\nocite@{#4@}@}%
4085 @AUCTeX{} will automatically figure out that @samp{newmacro} is a macro
4086 that takes five arguments. However, it is not smart enough to
4087 automatically see that each time we use the macro, two new macros are
4088 defined. We can specify this information in a style hook file.
4091 ;;; macro.el --- Special code for my own macro file.
4095 (defvar TeX-newmacro-regexp
4096 '("\\\\newmacro@{\\\\\\([a-zA-Z]+\\)@}@{\\\\\\([a-zA-Z]+\\)@}"
4097 (1 2) TeX-auto-multi)
4098 "Matches \newmacro definitions.")
4100 (defvar TeX-auto-multi nil
4101 "Temporary for parsing \\newmacro definitions.")
4103 (defun TeX-macro-cleanup ()
4104 "Move symbols from `TeX-auto-multi' to `TeX-auto-symbol'."
4105 (mapcar (lambda (list)
4106 (mapcar (lambda (symbol)
4107 (setq TeX-auto-symbol
4108 (cons symbol TeX-auto-symbol)))
4112 (defun TeX-macro-prepare ()
4113 "Clear `Tex-auto-multi' before use."
4114 (setq TeX-auto-multi nil))
4116 (add-hook 'TeX-auto-prepare-hook 'TeX-macro-prepare)
4117 (add-hook 'TeX-auto-cleanup-hook 'TeX-macro-cleanup)
4122 (TeX-auto-add-regexp TeX-newmacro-regexp)
4123 (TeX-add-symbols '("newmacro"
4125 (TeX-arg-macro "Capitalized macro: \\")
4130 ;;; macro.el ends here
4133 When this file is first loaded, it adds a new entry to
4134 @code{TeX-newmacro-regexp}, and defines a function to be called before
4135 the parsing starts, and one to be called after the parsing is done. It
4136 also declares a variable to contain the data collected during parsing.
4137 Finally, it adds a style hook which describes the @samp{newmacro} macro,
4138 as we have seen it before.
4140 So the general strategy is: Add a new entry to @code{TeX-newmacro-regexp}.
4141 Declare a variable to contain intermediate data during parsing. Add hook
4142 to be called before and after parsing. In this case, the hook before
4143 parsing just initializes the variable, and the hook after parsing
4144 collects the data from the variable, and adds them to the list of symbols
4147 @defvar TeX-auto-regexp-list
4148 List of regular expressions matching @TeX{} macro definitions.
4150 The list has the following format ((REGEXP MATCH TABLE) @dots{}), that
4151 is, each entry is a list with three elements.
4153 REGEXP. Regular expression matching the macro we want to parse.
4155 MATCH. A number or list of numbers, each representing one
4156 parenthesized subexpression matched by REGEXP.
4158 TABLE. The symbol table to store the data. This can be a function, in
4159 which case the function is called with the argument MATCH. Use
4160 @code{TeX-match-buffer} to get match data. If it is not a function, it
4161 is presumed to be the name of a variable containing a list of match
4162 data. The matched data (a string if MATCH is a number, a list of
4163 strings if MATCH is a list of numbers) is put in front of the table.
4166 @defvar TeX-auto-prepare-hook nil
4167 List of functions to be called before parsing a @TeX{} file.
4170 @defvar TeX-auto-cleanup-hook nil
4171 List of functions to be called after parsing a @TeX{} file.
4175 @appendix Copying, Changes, Development, FAQ
4178 * Copying this Manual::
4184 @node Copying this Manual
4185 @appendixsec Copying this Manual
4188 The copyright notice for this manual is:
4193 The full license text can be read here:
4196 * GNU Free Documentation License:: License for copying this manual.
4204 @appendixsec Changes and New Features
4207 @include changes.texi
4210 @subheading Older versions
4211 See the file @file{history.texi} for older changes.
4214 @appendixsec Future Development
4221 @appendixsec Frequently Asked Questions
4238 @unnumberedsec Key Index
4242 @node Function Index
4243 @unnumberedsec Function Index
4247 @node Variable Index
4248 @unnumberedsec Variable Index
4253 @unnumberedsec Concept Index