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-1995, 2001, 2002, 2004-2014
16 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
85 it 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, Texinfo mode
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
166 * Narrowing:: Restricting display and editing to a portion of the buffer
170 * Fontification of macros:: Fontification of macros
171 * Fontification of quotes:: Fontification of quotes
172 * Fontification of math:: Fontification of math constructs
173 * Verbatim content:: Verbatim macros and environments
174 * Faces:: Faces used by font-latex
176 Starting Processors, Viewers and Other Programs
178 * Commands:: Invoking external commands.
179 * Viewing:: Invoking external viewers.
180 * Debugging:: Debugging @TeX{} and @LaTeX{} output.
181 * Checking:: Checking the document.
182 * Control:: Controlling the processes.
183 * Cleaning:: Cleaning intermediate and output files.
184 * Documentation:: Documentation about macros and packages.
186 Viewing the Formatted Output
188 * Starting Viewers:: Starting viewers
189 * I/O Correlation:: Forward and inverse search
191 Customization and Extension
193 * Multifile:: Multifile Documents
194 * Parsing Files:: Automatic Parsing of @TeX{} Files
195 * Internationalization:: Language Support
196 * Automatic:: Automatic Customization
197 * Style Files:: Writing Your Own Style Support
201 * European:: Using @AUCTeX{} with European Languages
202 * Japanese:: Using @AUCTeX{} with Japanese
204 Automatic Customization
206 * Automatic Global:: Automatic Customization for the Site
207 * Automatic Private:: Automatic Customization for a User
208 * Automatic Local:: Automatic Customization for a Directory
210 Writing Your Own Style Support
212 * Simple Style:: A Simple Style File
213 * Adding Macros:: Adding Support for Macros
214 * Adding Environments:: Adding Support for Environments
215 * Adding Other:: Adding Other Information
216 * Hacking the Parser:: Automatic Extraction of New Things
218 Copying, Changes, Development, FAQ
220 * Copying this Manual::
228 * GNU Free Documentation License:: License for copying this manual.
245 @cindex General Public License
248 @cindex Free software
253 @c This text adapted from the Texinfo 2.16 distribution.
255 @AUCTeX{} primarily consists of Lisp files for Emacs (and XEmacs), but
256 there are also installation scripts and files and @TeX{} support files.
257 All of those are @dfn{free}; this means that everyone is free to use
258 them and free to redistribute them on a free basis. The files of
259 @AUCTeX{} are not in the public domain; they are copyrighted and there
260 are restrictions on their distribution, but these restrictions are
261 designed to permit everything that a good cooperating citizen would want
262 to do. What is not allowed is to try to prevent others from further
263 sharing any version of these programs that they might get from you.
265 Specifically, we want to make sure that you have the right to give away
266 copies of the files that constitute @AUCTeX{}, that you receive source
267 code or else can get it if you want it, that you can change these files
268 or use pieces of them in new free programs, and that you know you can do
271 To make sure that everyone has such rights, we have to forbid you to
272 deprive anyone else of these rights. For example, if you distribute
273 copies of parts of @AUCTeX{}, you must give the recipients all the
274 rights that you have. You must make sure that they, too, receive or can
275 get the source code. And you must tell them their rights.
277 Also, for our own protection, we must make certain that everyone finds
278 out that there is no warranty for @AUCTeX{}. If any parts are modified
279 by someone else and passed on, we want their recipients to know that
280 what they have is not what we distributed, so that any problems
281 introduced by others will not reflect on our reputation.
283 The precise conditions of the licenses for the files currently being
284 distributed as part of @AUCTeX{} are found in the General Public
285 Licenses that accompany them. This manual specifically is covered by
286 the GNU Free Documentation License (@pxref{Copying this Manual}).
289 @chapter Introduction
292 * Summary:: Overview of @AUCTeX{}
293 * Installation:: Installing @AUCTeX{}
294 * Quick Start:: Quick Start
300 @include install.texi
302 @include quickstart.texi
306 @chapter Editing the Document Source
308 The most commonly used commands/macros of @AUCTeX{} are those which
309 simply insert templates for often used @TeX{}, @LaTeX{}, or @ConTeXt{}
310 constructs, like font changes, handling of environments, etc. These
311 features are very simple, and easy to learn, and help you avoid mistakes
312 like mismatched braces, or @samp{\begin@{@}}-@samp{\end@{@}} pairs.
314 Apart from that this chapter contains a description of some features for
315 entering more specialized sorts of text, for formatting the source by
316 indenting and filling and for navigating through the document.
319 * Quotes:: Inserting quotes, dollars, and braces
320 * Font Specifiers:: Inserting Font Specifiers
321 * Sectioning:: Inserting chapters, sections, etc.
322 * Environments:: Inserting Environment Templates
323 * Mathematics:: Entering Mathematics
324 * Completion:: Completion of macros
325 * Marking:: Marking Environments, Sections, or Texinfo Nodes
326 * Commenting:: Commenting text
327 * Indenting:: Reflecting syntactic constructs with whitespace
328 * Filling:: Automatic and manual line breaking
332 @section Insertion of Quotes, Dollars, and Braces
335 @cindex Double quotes
339 @cindex Math mode delimiters
340 @cindex Matching dollar signs
341 @cindex Display math mode
343 @subheading Quotation Marks
345 In @TeX{}, literal double quotes @samp{"like this"} are seldom used,
346 instead two single quotes are used @samp{``like this''}. To help you
347 insert these efficiently, @AUCTeX{} allows you to continue to press
348 @kbd{"} to insert two single quotes. To get a literal double quote,
351 @deffn Command TeX-insert-quote @var{count}
353 (@kbd{"}) Insert the appropriate quote marks for @TeX{}.
355 Inserts the value of @code{TeX-open-quote} (normally @samp{``}) or
356 @code{TeX-close-quote} (normally @samp{''}) depending on the context.
357 With prefix argument, always inserts @samp{"} characters.
360 @defopt TeX-open-quote
361 String inserted by typing @kbd{"} to open a quotation.
362 (@xref{European}, for language-specific quotation mark insertion.)
365 @defopt TeX-close-quote
366 String inserted by typing @kbd{"} to close a quotation.
367 (@xref{European}, for language-specific quotation mark insertion.)
370 @defopt TeX-quote-after-quote
371 Determines the behavior of @kbd{"}. If it is non-nil, typing @kbd{"}
372 will insert a literal double quote. The respective values of
373 @code{TeX-open-quote} and @code{TeX-close-quote} will be inserted
374 after typing @kbd{"} once again.
377 The @samp{babel} package provides special support for the requirements
378 of typesetting quotation marks in many different languages. If you use
379 this package, either directly or by loading a language-specific style
380 file, you should also use the special commands for quote insertion
381 instead of the standard quotes shown above. @AUCTeX{} is able to
382 recognize several of these languages and will change quote insertion
383 accordingly. @xref{European}, for details about this feature and how to
386 @vindex LaTeX-csquotes-open-quote
387 @vindex LaTeX-csquotes-close-quote
388 @vindex LaTeX-csquotes-quote-after-quote
389 In case you are using the @samp{csquotes} package, you should customize
390 @code{LaTeX-csquotes-open-quote}, @code{LaTeX-csquotes-close-quote} and
391 @code{LaTeX-csquotes-quote-after-quote}. The quotation characters will
392 only be used if both variables---@code{LaTeX-csquotes-open-quote} and
393 @code{LaTeX-csquotes-close-quote}---are non-empty strings. But then the
394 @samp{csquotes}-related values will take precedence over the
395 language-specific ones.
397 @subheading Dollar Signs
399 In @AUCTeX{}, dollar signs should match like they do in @TeX{}. This
400 has been partially implemented, we assume dollar signs always match
401 within a paragraph. By default, the first @samp{$} you insert in a
402 paragraph will do nothing special. The second @samp{$} will match the
403 first. This will be indicated by moving the cursor temporarily over the
406 @deffn Command TeX-insert-dollar @var{arg}
408 (@kbd{$}) Insert dollar sign.
410 Show matching dollar sign if this dollar sign end the @TeX{} math mode.
412 With optional @var{arg}, insert that many dollar signs.
415 @TeX{} and @LaTeX{} users often look for a way to insert inline
416 equations like @samp{$...$} or @samp{\(...\)} simply typing @kbd{$}.
417 @AUCTeX{} helps them through the customizable variable
418 @code{TeX-electric-math}.
420 @defopt TeX-electric-math
421 If the variable is non-nil and you type @kbd{$} outside math mode,
422 @AUCTeX{} will automatically insert the opening and closing symbols for
423 an inline equation and put the point between them. The opening symbol
424 will blink when @code{blink-matching-paren} is non-nil. If
425 @code{TeX-electric-math} is nil, typing @kbd{$} simply inserts @samp{$}
426 at point, this is the default.
428 Besides @code{nil}, possible values for this variable are @code{(cons
429 "$" "$")} for @TeX{} inline equations @samp{$...$}, and @code{(cons
430 "\\(" "\\)")} for @LaTeX{} inline equations @samp{\(...\)}.
432 If the variable is non-nil and point is inside math mode right between a
433 couple of single dollars, pressing @kbd{$} will insert another pair of
434 dollar signs and leave the point between them. Thus, if
435 @code{TeX-electric-math} is set to @code{(cons "$" "$")} you can easily
436 obtain a @TeX{} display equation @samp{$$...$$} by pressing @kbd{$}
437 twice in a row. (Note that you should not use double dollar signs in
438 @LaTeX{} because this practice can lead to wrong spacing in typeset
441 In addition, when the variable is non-nil and there is an active region
442 outside math mode, typing @kbd{$} will put around the active region
443 symbols for opening and closing inline equation and keep the region
444 active, leaving point after the closing symbol. By pressing repeatedly
445 @kbd{$} while the region is active you can toggle between an inline
446 equation, a display equation, and no equation. To be precise,
447 @samp{$...$} is replaced by @samp{$$...$$}, whereas @samp{\(...\)} is
448 replaced by @samp{\[...\]}.
451 If you want to automatically insert @samp{$...$} in plain @TeX{} files,
452 and @samp{\(...\)} in @LaTeX{} files by pressing @kbd{$}, add the
453 following to your init file
455 (add-hook 'plain-TeX-mode-hook
456 (lambda () (set (make-variable-buffer-local 'TeX-electric-math)
458 (add-hook 'LaTeX-mode-hook
459 (lambda () (set (make-variable-buffer-local 'TeX-electric-math)
460 (cons "\\(" "\\)"))))
465 To avoid unbalanced braces, it is useful to insert them pairwise. You
466 can do this by typing @kbd{C-c @{}.
468 @deffn Command TeX-insert-braces
470 (@kbd{C-c @{}) Make a pair of braces and position the cursor
471 to type inside of them. If there is an active region, put braces around
472 it and leave point after the closing brace.
475 When writing complex math formulas in @LaTeX{} documents, you
476 sometimes need to adjust the size of braces with pairs of macros like
477 @samp{\left}-@samp{\right}, @samp{\bigl}-@samp{\bigr} and so on. You
478 can avoid unbalanced pairs with the help of @code{TeX-insert-macro},
479 bound to @kbd{C-c C-m} or @kbd{C-c @key{RET}} (@pxref{Completion}).
480 If you insert left size adjusting macros such as @samp{\left},
481 @samp{\bigl} etc. with @code{TeX-insert-macro}, it asks for left brace
482 to use and supplies automatically right size adjusting macros such as
483 @samp{\right}, @samp{\bigr} etc. and corresponding right brace in
484 addtion to the intended left macro and left brace.
486 The completion by @code{TeX-insert-macro} also applies when entering
487 macros such as @samp{\langle}, @samp{\lfloor} and @samp{\lceil}, which
488 produce the left part of the paired braces. For example, inserting
489 @samp{\lfloor} by @kbd{C-c C-m} is immediately followed by the
490 insertion of @samp{\rfloor}. In addition, if the point was located
491 just after @samp{\left} or its friends, the corresponding
492 @samp{\right} etc. will be inserted in front of @samp{\rfloor}.
493 In both cases, active region is honored.
495 As a side effect, when @code{LaTeX-math-mode} (@pxref{Mathematics}) is
496 on, just typing @kbd{`(} inserts not only @samp{\langle}, but also
499 If you do not like such auto completion at all, it can be disabled by a
502 @defopt TeX-arg-right-insert-p
503 If this option is turned off, the automatic supply of the right macros
504 and braces is suppressed.
507 When you edit @LaTeX{} documents, you can enable automatic brace
508 pairing when typing @kbd{(}, @kbd{@{} and @kbd{[}.
510 @defopt LaTeX-electric-left-right-brace
511 If this option is on, just typing @kbd{(}, @kbd{@{} or @kbd{[}
512 immediately adds the corresponding right brace @samp{)}, @samp{@}} or
513 @samp{]}. The point is left after the opening brace. If there is an
514 active region, braces are put around it.
516 They recognize the preceeding backslash or size adjusting macros such
517 as @samp{\left}, @samp{\bigl} etc., so the following completions will
522 (when typing single left brace)
526 @samp{(} -> @samp{()}
529 @samp{@{} -> @samp{@{@}}
532 @samp{[} -> @samp{[]}
536 (when typing left brace just after a backslash)
540 @samp{\(} -> @samp{\(\)}
543 @samp{\@{} -> @samp{\@{\@}}
546 @samp{\[} -> @samp{\[\]}
550 (when typing just after @samp{\left} or @samp{\bigl})
554 @samp{\left(} -> @samp{\left(\right)}
557 @samp{\bigl[} -> @samp{\bigl[\bigr]}
561 (when typing just after @samp{\Bigl\})
565 @samp{\Bigl\@{} -> @samp{\Bigl\@{\Bigr\@}}
571 This auto completion feature may be a bit annoying when editing an
572 already existing @LaTeX{} document. In that case, use @kbd{C-u 1} or
573 @kbd{C-q} before typing @kbd{(}, @kbd{@{} or @kbd{[}. Then no
574 completion is done and just a single left brace is inserted. In fact,
575 with optional prefix @var{arg}, just that many open braces are
576 inserted without any completion.
579 @node Font Specifiers
580 @section Inserting Font Specifiers
584 @cindex Changing font
585 @cindex Specifying a font
587 Perhaps the most used keyboard commands of @AUCTeX{} are the short-cuts
588 available for easy insertion of font changing macros.
590 If you give an argument (that is, type @kbd{C-u}) to the font command,
591 the innermost font will be replaced, i.e. the font in the @TeX{} group
592 around point will be changed. The following table shows the available
593 commands, with @code{@point{}} indicating the position where the text
599 @cindex @code{\textbf}
600 Insert @b{bold face} @samp{\textbf@{@point{}@}} text.
604 @cindex @code{\textit}
605 Insert @i{italics} @samp{\textit@{@point{}@}} text.
610 Insert @i{emphasized} @samp{\emph@{@point{}@}} text.
614 @cindex @code{\textsl}
615 Insert @i{slanted} @samp{\textsl@{@point{}@}} text.
619 @cindex @code{\textrm}
620 Insert roman @r{\textrm@{@point{}@}} text.
624 @cindex @code{\textsf}
625 Insert @sansserif{sans serif} @samp{\textsf@{@point{}@}} text.
629 @cindex @code{\texttt}
630 Insert @t{typewriter} @samp{\texttt@{@point{}@}} text.
634 @cindex @code{\textsc}
635 Insert @sc{small caps} @samp{\textsc@{@point{}@}} text.
639 @cindex Deleting fonts
640 Delete the innermost font specification containing point.
644 @deffn Command TeX-font replace what
646 (@kbd{C-c C-f}) Insert template for font change command.
648 If @var{replace} is not nil, replace current font. @var{what}
649 determines the font to use, as specified by @code{TeX-font-list}.
652 @defopt TeX-font-list
653 List of fonts used by @code{TeX-font}.
655 Each entry is a list with three elements. The first element is the
656 key to activate the font. The second element is the string to insert
657 before point, and the third element is the string to insert after
658 point. An optional fourth element means always replace if not nil.
661 @defopt LaTeX-font-list
662 List of fonts used by @code{TeX-font} in LaTeX mode. It has the same
663 structure as @code{TeX-font-list}.
667 @section Inserting chapters, sections, etc.
671 @cindex @code{\chapter}
672 @cindex @code{\section}
673 @cindex @code{\subsection}
674 @cindex @code{\label}
676 Insertion of sectioning macros, that is @samp{\chapter},
677 @samp{\section}, @samp{\subsection}, etc. and accompanying
678 @samp{\label}'s may be eased by using @kbd{C-c C-s}. This command is
679 highly customizable, the following describes the default behavior.
681 When invoking you will be asked for a section macro to insert. An
682 appropriate default is automatically selected by @AUCTeX{}, that is
683 either: at the top of the document; the top level sectioning for that
684 document style, and any other place: The same as the last occurring
687 Next, you will be asked for the actual name of that section, and last
688 you will be asked for a label to be associated with that section. The
689 label will be prefixed by the value specified in
690 @code{LaTeX-section-hook}.
692 @deffn Command LaTeX-section @var{arg}
694 (@kbd{C-c C-s}) Insert a sectioning command.
696 Determine the type of section to be inserted, by the argument
701 If @var{arg} is nil or missing, use the current level.
703 If @var{arg} is a list (selected by C-u), go downward one level.
705 If @var{arg} is negative, go up that many levels.
707 If @var{arg} is positive or zero, use absolute level:
726 The following variables can be set to customize the function.
729 @item LaTeX-section-hook
730 Hooks to be run when inserting a section.
731 @item LaTeX-section-label
732 Prefix to all section references.
737 The precise behavior of @code{LaTeX-section} is defined by the contents
738 of @code{LaTeX-section-hook}.
740 @defopt LaTeX-section-hook
741 List of hooks to run when a new section is inserted.
743 The following variables are set before the hooks are run
747 Numeric section level, default set by prefix arg to
748 @code{LaTeX-section}.
750 Name of the sectioning command, derived from @var{level}.
752 The title of the section, default to an empty string.
754 Entry for the table of contents list, default nil.
756 Position of point afterwards, default nil meaning after the inserted
760 A number of hooks are already defined. Most likely, you will be able to
761 get the desired functionality by choosing from these hooks.
764 @item LaTeX-section-heading
765 Query the user about the name of the sectioning command. Modifies
766 @var{level} and @var{name}.
767 @item LaTeX-section-title
768 Query the user about the title of the section. Modifies @var{title}.
769 @item LaTeX-section-toc
770 Query the user for the toc entry. Modifies @var{toc}.
771 @item LaTeX-section-section
772 Insert @LaTeX{} section command according to @var{name}, @var{title},
773 and @var{toc}. If @var{toc} is nil, no toc entry is inserted. If
774 @var{toc} or @var{title} are empty strings, @var{done-mark} will be
775 placed at the point they should be inserted.
776 @item LaTeX-section-label
777 Insert a label after the section command. Controlled by the variable
778 @code{LaTeX-section-label}.
781 To get a full featured @code{LaTeX-section} command, insert
784 (setq LaTeX-section-hook
785 '(LaTeX-section-heading
788 LaTeX-section-section
789 LaTeX-section-label))
792 in your @file{.emacs} file.
795 The behavior of @code{LaTeX-section-label} is determined by the
796 variable @code{LaTeX-section-label}.
798 @defopt LaTeX-section-label
799 Default prefix when asking for a label.
801 If it is a string, it is used unchanged for all kinds of sections.
802 If it is nil, no label is inserted.
803 If it is a list, the list is searched for a member whose car is equal
804 to the name of the sectioning command being inserted. The cdr is then
805 used as the prefix. If the name is not found, or if the cdr is nil,
806 no label is inserted.
808 @cindex Prefix for labels
811 By default, chapters have a prefix of @samp{cha:} while sections and
812 subsections have a prefix of @samp{sec:}. Labels are not automatically
813 inserted for other types of sections.
817 @section Inserting Environment Templates
819 @cindex @samp{\begin}
822 A large apparatus is available that supports insertions of environments,
823 that is @samp{\begin@{@}} --- @samp{\end@{@}} pairs.
825 @AUCTeX{} is aware of most of the actual environments available in a
826 specific document. This is achieved by examining your
827 @samp{\documentclass} command, and consulting a precompiled list of
828 environments available in a large number of styles.
830 Most of these are described further in the following sections, and you
831 may easily specify more. @xref{Customizing Environments}.
833 You insert an environment with @kbd{C-c C-e}, and select an environment
834 type. Depending on the environment, @AUCTeX{} may ask more questions
835 about the optional parts of the selected environment type. With
836 @kbd{C-u C-c C-e} you will change the current environment.
838 @deffn Command LaTeX-environment @var{arg}
840 (@kbd{C-c C-e}) @AUCTeX{} will prompt you for an environment
841 to insert. At this prompt, you may press @key{TAB} or @key{SPC} to
842 complete a partially written name, and/or to get a list of available
843 environments. After selection of a specific environment @AUCTeX{} may
844 prompt you for further specifications.
846 If the optional argument @var{arg} is not-nil (i.e. you have given a
847 prefix argument), the current environment is modified and no new
848 environment is inserted.
851 @AUCTeX{} helps you adding labels to environments which use them, such
852 as @samp{equation}, @samp{figure}, @samp{table}, etc@dots{} When you
853 insert one of the supported environments with @kbd{C-c C-e}, you will be
854 automatically prompted for a label. You can select the prefix to be
855 used for such environments with the @code{LaTeX-label-alist} variable.
856 @defopt LaTeX-label-alist
857 List the prefixes to be used for the label of each supported
860 This is an alist whose car is the environment name, and the cdr either
861 the prefix or a symbol referring to one.
863 If the name is not found, or if the cdr is nil, no label is
864 automatically inserted for that environment.
866 If you want to automatically insert a label for a environment but with
867 an empty prefix, use the empty string @code{""} as the cdr of the
871 As a default selection, @AUCTeX{} will suggest the environment last
872 inserted or, as the first choice the value of the variable
873 @code{LaTeX-default-environment}.
875 @defopt LaTeX-default-environment
876 Default environment to insert when invoking @samp{LaTeX-environment}
877 first time. When the current environment is @samp{document}, it is
878 overriden by @code{LaTeX-default-document-environment}.
881 @defvar LaTeX-default-document-environment
882 Default environment when invoking @samp{LaTeX-environment} and the
883 current environment is @samp{document}. It is intended to be used in
884 @LaTeX{} class style files. For example, in @file{beamer.el} it is set
885 to @code{frame}, in @file{letter.el} to @code{letter}, and in
886 @file{slides.el} to @code{slide}.
889 If the document is empty, or the cursor is placed at the top of the
890 document, @AUCTeX{} will default to insert a @samp{document} environment
891 prompting also for the insertion of @samp{\documentclass} and
892 @samp{\usepackage} macros. You will be prompted for a new package until
893 you enter nothing. If you do not want to insert any @samp{\usepackage}
894 at all, just press @key{RET} at the first @samp{Packages} prompt.
896 @AUCTeX{} distinguishes normal and expert environments. By default, it
897 will offer completion only for normal environments. This behavior is
898 controlled by the user option @code{TeX-complete-expert-commands}.
900 @defopt TeX-complete-expert-commands
901 Complete macros and environments marked as expert commands.
903 Possible values are nil, t, or a list of style names.
907 Don't complete expert commands (default).
909 Always complete expert commands.
910 @item (STYLES @dots{})
911 Only complete expert commands of STYLES.
917 * Equations:: Equations
919 * Itemize-like:: Itemize-like Environments
920 * Tabular-like:: Tabular-like Environments
921 * Customizing Environments:: Customizing Environments
924 You can close the current environment with @kbd{C-c ]}, but we suggest
925 that you use @kbd{C-c C-e} to insert complete environments instead.
927 @deffn Command LaTeX-close-environment
929 (@kbd{C-c ]}) Insert an @samp{\end} that matches the current environment.
932 @AUCTeX{} offers keyboard shortcuts for moving point to the beginning
933 and to the end of the current environment.
934 @deffn Command LaTeX-find-matching-begin
936 (@kbd{C-M-a}) Move point to the @samp{\begin} of the current
939 If this command is called inside a comment and
940 @code{LaTeX-syntactic-comments} is enabled, try to find the environment
941 in commented regions with the same comment prefix.
944 @deffn Command LaTeX-find-matching-end
946 (@kbd{C-M-e}) Move point to the @samp{\end} of the current environment.
948 If this command is called inside a comment and
949 @code{LaTeX-syntactic-comments} is enabled, try to find the environment
950 in commented regions with the same comment prefix.
954 @subsection Equations
960 When inserting equation-like environments, the @samp{\label} will have a
961 default prefix, which is controlled by the following variables:
963 @defopt LaTeX-equation-label
964 Prefix to use for `equation' labels.
967 @defopt LaTeX-eqnarray-label
968 Prefix to use for `eqnarray' labels.
971 @defopt LaTeX-amsmath-label
972 Prefix to use for amsmath equation labels. Amsmath equations include
973 @samp{align}, @samp{alignat}, @samp{xalignat}, @samp{aligned},
974 @samp{flalign} and @samp{gather}.
981 @cindex Figure environment
983 @cindex Table environment
985 Figures and tables (i.e., floats) may also be inserted using @AUCTeX{}.
986 After choosing either `figure' or `table' in the environment list
987 described above, you will be prompted for a number of additional things.
991 This is the optional argument of float environments that controls how
992 they are placed in the final document. In @LaTeX{} this is a sequence
993 of the letters @samp{htbp} as described in the @LaTeX{} manual. The
994 value will default to the value of @code{LaTeX-float}.
998 This is the caption of the float. The default is to insert the caption
999 at the bottom of the float. You can specify floats where the caption
1000 should be placed at the top with @code{LaTeX-top-caption-list}.
1001 @vindex LaTeX-top-caption-list
1004 The label of this float. The label will have a default prefix, which is
1005 controlled by the variables @code{LaTeX-figure-label} and
1006 @code{LaTeX-table-label}.
1007 @vindex LaTeX-figure-label
1008 @vindex LaTeX-table-label
1009 @cindex Prefix for labels
1010 @cindex Label prefix
1014 Moreover, you will be asked if you want the contents of the float
1015 environment to be horizontally centered. Upon a positive answer a
1016 @samp{\centering} macro will be inserted at the beginning of the float
1020 Default placement for floats.
1023 @defopt LaTeX-figure-label
1024 Prefix to use for figure labels.
1027 @defopt LaTeX-table-label
1028 Prefix to use for table labels.
1031 @defopt LaTeX-top-caption-list
1032 List of float environments with top caption.
1036 @subsection Itemize-like Environments
1039 @cindex Descriptions
1043 In an itemize-like environment, nodes (i.e., @samp{\item}s) may be
1044 inserted using @kbd{C-c @key{LFD}}.
1046 @deffn Command LaTeX-insert-item
1047 @kindex C-c @key{LFD}
1048 (@kbd{C-c @key{LFD}}) Close the current item, move to the next line and
1049 insert an appropriate @samp{\item} for the current environment. That is,
1050 `itemize' and `enumerate' will have @samp{\item } inserted, while
1051 `description' will have @samp{\item[]} inserted.
1054 @defopt TeX-arg-item-label-p
1055 If non-nil, you will always be asked for optional label in items.
1056 Otherwise, you will be asked only in description environments.
1060 @subsection Tabular-like Environments
1063 When inserting Tabular-like environments, that is, `tabular' `array'
1064 etc., you will be prompted for a template for that environment.
1067 @defopt LaTeX-default-format
1068 Default format string for array and tabular environments.
1071 @defopt LaTeX-default-width
1072 Default width for minipage and tabular* environments.
1075 @defopt LaTeX-default-position
1076 Default position string for array and tabular environments. If nil,
1077 act like the empty string is given, but don't prompt for a position.
1080 @AUCTeX{} calculates the number of columns from the format string and
1081 inserts the suitable number of ampersands.
1083 You can use @kbd{C-c @key{LFD}} (@code{LaTeX-insert-item}) to terminate
1084 rows in these environments. It supplies line break macro @samp{\\} and
1085 inserts the suitable number of ampersands on the next line.
1087 @deffn Command LaTeX-insert-item
1088 @kindex C-c @key{LFD}
1089 (@kbd{C-c @key{LFD}}) Close the current row with @samp{\\}, move to the
1090 next line and insert an appropriate number of ampersands for the current
1094 Similar supports are provided for various amsmath environments such as
1095 @samp{align}, @samp{gather}, @samp{alignat}, @samp{matrix} etc. Try
1096 typing @kbd{C-c @key{LFD}} in these environments. It recognizes the
1097 current environment and does the appropriate job depending on the
1100 @node Customizing Environments
1101 @subsection Customizing Environments
1103 @xref{Adding Environments}, for how to customize the list of known
1107 @section Entering Mathematics
1110 @cindex Abbreviations
1112 @TeX{} is written by a mathematician, and has always contained good
1113 support for formatting mathematical text. @AUCTeX{} supports this
1114 tradition, by offering a special minor mode for entering text with many
1115 mathematical symbols. You can enter this mode by typing @kbd{C-c
1118 @deffn Command LaTeX-math-mode
1120 (@kbd{C-c ~}) Toggle LaTeX Math mode. This is a minor mode rebinding
1121 the key @code{LaTeX-math-abbrev-prefix} to allow easy typing of
1122 mathematical symbols. @kbd{`} will read a character from the keyboard,
1123 and insert the symbol as specified in @code{LaTeX-math-default} and
1124 @code{LaTeX-math-list}. If given a prefix argument, the symbol will be
1125 surrounded by dollar signs.
1128 You can use another prefix key (instead of @kbd{`}) by setting the
1129 variable @code{LaTeX-math-abbrev-prefix}.
1131 To enable LaTeX Math mode by default, add the following in your
1134 (add-hook 'LaTeX-mode-hook 'LaTeX-math-mode)
1137 @defopt LaTeX-math-abbrev-prefix
1138 A string containing the prefix of @code{LaTeX-math-mode} commands; This
1139 value defaults to @kbd{`}.
1141 The string has to be a key or key sequence in a format understood by the
1142 @code{kbd} macro. This corresponds to the syntax usually used in the
1143 manuals for Emacs Emacs Lisp.
1146 The variable @code{LaTeX-math-list} allows you to add your own mappings.
1148 @defopt LaTeX-math-list
1149 A list containing user-defined keys and commands to be used in LaTeX
1150 Math mode. Each entry should be a list of two to four elements.
1152 First, the key to be used after @code{LaTeX-math-abbrev-prefix} for
1153 macro insertion. If it is nil, the symbol has no associated
1154 keystroke (it is available in the menu, though).
1156 Second, a string representing the name of the macro (without a leading
1159 Third, a string representing the name of a submenu the command should be
1160 added to. Use a list of strings in case of nested menus.
1162 Fourth, the position of a Unicode character to be displayed in the menu
1163 alongside the macro name. This is an integer value.
1166 @defopt LaTeX-math-menu-unicode
1167 Whether the LaTeX menu should try using Unicode for effect. Your Emacs
1168 built must be able to display include Unicode characters in menus for
1172 @AUCTeX{}'s reference card @file{tex-ref.tex} includes a list of all
1175 @AUCTeX{} can help you write subscripts and superscripts in math
1176 constructs by automatically inserting a pair of braces after typing
1177 @key{_} or @key{^} respectively and putting point between the braces.
1178 In order to enable this feature, set the variable
1179 @code{TeX-electric-sub-and-superscript} to a non-nil value.
1181 @defopt TeX-electric-sub-and-superscript
1182 If non-nil, insert braces after typing @key{^} and @key{_} in math mode.
1189 @cindex Macro expansion
1190 @cindex Macro completion
1191 @cindex Macro arguments
1192 @cindex Arguments to @TeX{} macros
1194 Emacs lisp programmers probably know the @code{lisp-complete-symbol}
1195 command, usually bound to @kbd{M-@key{TAB}}. Users of the wonderful
1196 ispell mode know and love the @code{ispell-complete-word} command from
1197 that package. Similarly, @AUCTeX{} has a @code{TeX-complete-symbol}
1198 command, by default bound to @kbd{M-@key{TAB}} which is equivalent to
1199 @kbd{M-C-i}. Using @code{TeX-complete-symbol} makes it easier to type
1200 and remember the names of long @LaTeX{} macros.
1202 In order to use @code{TeX-complete-symbol}, you should write a backslash
1203 and the start of the macro. Typing @kbd{M-@key{TAB}} will now complete
1204 as much of the macro, as it unambiguously can. For example, if you type
1205 `@samp{\renewc}' and then @kbd{M-@key{TAB}}, it will expand to
1206 `@samp{\renewcommand}'.
1208 @deffn Command TeX-complete-symbol
1210 (@kbd{M-@key{TAB}}) Complete @TeX{} symbol before point.
1213 A more direct way to insert a macro is with @code{TeX-insert-macro},
1214 bound to @kbd{C-c C-m} which is equivalent to @kbd{C-c @key{RET}}. It
1215 has the advantage over completion that it knows about the argument of
1216 most standard @LaTeX{} macros, and will prompt for them. It also knows
1217 about the type of the arguments, so it will for example give completion
1218 for the argument to @samp{\include}. Some examples are listed below.
1220 @deffn Command TeX-insert-macro
1222 (@kbd{C-c C-m} or @kbd{C-c @key{RET}}) Prompt (with completion) for the
1223 name of a @TeX{} macro, and if @AUCTeX{} knows the macro, prompt for
1227 As a default selection, @AUCTeX{} will suggest the macro last inserted
1228 or, as the first choice the value of the variable
1229 @code{TeX-default-macro}.
1231 @defopt TeX-insert-macro-default-style
1232 Specifies whether @code{TeX-insert-macro} will ask for all optional
1235 If set to the symbol @code{show-optional-args}, @code{TeX-insert-macro}
1236 asks for optional arguments of @TeX{} marcos, unless the previous
1237 optional argument has been rejected. If set to
1238 @code{show-all-optional-args}, @code{TeX-insert-macro} asks for all
1239 optional arguments. @code{mandatory-args-only}, @code{TeX-insert-macro}
1240 asks only for mandatory arguments. When @code{TeX-insert-macro} is
1241 called with prefix argument (@kbd{C-u}), it's the other way round.
1243 Note that for some macros, there are special mechanisms, e.g.
1244 @code{LaTeX-includegraphics-options-alist} and
1245 @code{TeX-arg-cite-note-p}.
1250 @defopt TeX-default-macro
1251 Default macro to insert when invoking @code{TeX-insert-macro} first time.
1254 A faster alternative is to bind the function @code{TeX-electric-macro}
1255 to @samp{\}. This can be done by setting the variable
1256 @code{TeX-electric-escape}
1258 @defopt TeX-electric-escape
1259 If this is non-nil when @AUCTeX{} is loaded, the @TeX{} escape
1260 character @samp{\} will be bound to @code{TeX-electric-macro}
1263 The difference between @code{TeX-insert-macro} and
1264 @code{TeX-electric-macro} is that space will complete and exit from the
1265 minibuffer in @code{TeX-electric-macro}. Use @key{TAB} if you merely
1268 @deffn Command TeX-electric-macro
1269 Prompt (with completion) for the name of a @TeX{} macro,
1270 and if @AUCTeX{} knows the macro, prompt for each argument.
1271 Space will complete and exit.
1274 By default @AUCTeX{} will put an empty set braces @samp{@{@}} after a
1275 macro with no arguments to stop it from eating the next whitespace.
1276 This can be stopped by entering @code{LaTeX-math-mode},
1277 @pxref{Mathematics}, or by setting @code{TeX-insert-braces} to nil.
1279 @defopt TeX-insert-braces
1280 If non-nil, append a empty pair of braces after inserting a macro.
1283 @defopt TeX-insert-braces-alist
1284 Control the insertion of a pair of braces after a macro on a per macro
1287 This variable is an alist. Each element is a cons cell, whose car is
1288 the macro name, and the cdr is non-nil or nil, depending on whether a
1289 pair of braces should be, respectively, appended or not to the macro.
1291 If a macro has an element in this variable, @code{TeX-parse-macro} will
1292 use its value to decided what to do, whatever the value of the variable
1293 @code{TeX-insert-braces}.
1296 Completions work because @AUCTeX{} can analyze @TeX{} files, and store
1297 symbols in Emacs Lisp files for later retrieval. @xref{Automatic}, for
1300 @AUCTeX{} distinguishes normal and expert macros. By default, it will
1301 offer completion only for normal commands. This behavior can be
1302 controlled using the user option @code{TeX-complete-expert-commands}.
1304 @defopt TeX-complete-expert-commands
1305 Complete macros and environments marked as expert commands.
1307 Possible values are nil, t, or a list of style names.
1311 Don't complete expert commands (default).
1313 Always complete expert commands.
1314 @item (STYLES @dots{})
1315 Only complete expert commands of STYLES.
1320 @cindex \cite, completion of
1321 @cindex Bib@TeX{}, completion
1322 @cindex cite, completion of
1323 @cindex bibliography, completion
1324 @cindex citations, completion of
1325 @cindex \label, completion
1326 @cindex \ref, completion
1327 @cindex labels, completion of
1328 @AUCTeX{} will also make completion for many macro arguments, for
1329 example existing labels when you enter a @samp{\ref} macro with
1330 @code{TeX-insert-macro} or @code{TeX-electric-macro}, and Bib@TeX{}
1331 entries when you enter a @samp{\cite} macro. For this kind of
1332 completion to work, parsing must be enabled as described in
1333 @pxref{Parsing Files}. For @samp{\cite} you must also make sure that
1334 the Bib@TeX{} files have been saved at least once after you enabled
1335 automatic parsing on save, and that the basename of the Bib@TeX{} file
1336 does not conflict with the basename of one of @TeX{} files.
1339 @section Marking Environments, Sections, or Texinfo Nodes
1341 You can mark the current environment by typing @kbd{C-c .}, or the
1342 current section by typing @kbd{C-c *}.
1344 In Texinfo documents you can type @kbd{M-C-h} to mark the current node.
1346 When the region is set, the point is moved to its beginning and the mark
1350 * Marking (LaTeX):: LaTeX Commands for Marking Environments and Sections
1351 * Marking (Texinfo):: Texinfo Commands for Marking Environments, Sections, and Nodes
1354 @node Marking (LaTeX)
1355 @subsection LaTeX Commands for Marking Environments and Sections
1357 @deffn Command LaTeX-mark-section
1359 (@kbd{C-c *}) Set mark at end of current logical section, and point at
1362 With a non-nil prefix argument, mark only the region from the current
1363 section start to the next sectioning command. Thereby subsections are
1364 not being marked. Otherwise, any included subsections are also marked
1365 along with current section.
1368 @deffn Command LaTeX-mark-environment
1370 (@kbd{C-c .}) Set mark to the end of the current environment and point
1371 to the matching beginning.
1373 If a prefix argument is given, mark the respective number of enclosing
1374 environments. The command will not work properly if there are
1375 unbalanced begin-end pairs in comments and verbatim environments.
1378 @node Marking (Texinfo)
1379 @subsection Texinfo Commands for Marking Environments and Sections
1381 @deffn Command Texinfo-mark-section
1383 (@kbd{C-c *}) Mark the current section, with inclusion of any containing
1386 The current section is detected as starting by any of the structuring
1387 commands matched by the regular expression in the variable
1388 @code{outline-regexp} which in turn is a regular expression matching any
1389 element of the variable @code{texinfo-section-list}.
1391 With a non-nil prefix argument, mark only the region from the current
1392 section start to the next sectioning command. Thereby subsections are
1393 not being marked. Otherwise, any included subsections are also marked
1395 Note that when the current section is starting immediately after a node
1396 command, then the node command is also marked as part of the section.
1399 @deffn Command Texinfo-mark-environment
1401 (@kbd{C-c .}) Set mark to the end of the current environment and point
1402 to the matching beginning.
1404 If a prefix argument is given, mark the respective number of enclosing
1405 environments. The command will not work properly if there are
1406 unbalanced begin-end pairs in comments and verbatim environments.
1409 @deffn Command Texinfo-mark-node
1411 (@kbd{M-C-h}) Mark the current node. This is the node in which point is
1412 located. It is starting at the previous occurrence of the keyword
1413 @code{@@node} and ending at next occurrence of the keywords
1414 @code{@@node} or @code{@@bye}.
1420 It is often necessary to comment out temporarily a region of @TeX{} or
1421 @LaTeX{} code. This can be done with the commands @kbd{C-c ;} and
1422 @kbd{C-c %}. @kbd{C-c ;} will comment out all lines in the current
1423 region, while @kbd{C-c %} will comment out the current paragraph.
1424 Type @kbd{C-c ;} again to uncomment all lines of a commented region,
1425 or @kbd{C-c %} again to uncomment all comment lines around point.
1426 These commands will insert or remove a single @samp{%} respectively.
1428 @deffn Command TeX-comment-or-uncomment-region
1430 (@kbd{C-c ;}) Add or remove @samp{%} from the beginning of each line
1431 in the current region. Uncommenting works only if the region encloses
1432 solely commented lines. If @AUCTeX{} should not try to guess if the
1433 region should be commented or uncommented the commands
1434 @code{TeX-comment-region} and @code{TeX-uncomment-region} can be used
1435 to explicitly comment or uncomment the region in concern.
1438 @deffn Command TeX-comment-or-uncomment-paragraph
1440 (@kbd{C-c %}) Add or remove @samp{%} from the beginning of each line
1441 in the current paragraph. When removing @samp{%} characters the
1442 paragraph is considered to consist of all preceding and succeeding
1443 lines starting with a @samp{%}, until the first non-comment line.
1451 @cindex Reformatting
1454 Indentation means the addition of whitespace at the beginning of lines
1455 to reflect special syntactical constructs. This makes it easier to see
1456 the structure of the document, and to catch errors such as a missing
1457 closing brace. Thus, the indentation is done for precisely the same
1458 reasons that you would indent ordinary computer programs.
1460 Indentation is done by @LaTeX{} environments and by @TeX{} groups, that
1461 is the body of an environment is indented by the value of
1462 @code{LaTeX-indent-level} (default 2). Also, items of an `itemize-like'
1463 environment are indented by the value of @code{LaTeX-item-indent},
1464 default @minus{}2. (Items are identified with the help of
1465 @code{LaTeX-item-regexp}.) If more environments are nested, they are
1466 indented `accumulated' just like most programming languages usually are
1467 seen indented in nested constructs.
1468 @vindex LaTeX-indent-level
1469 @vindex LaTeX-item-indent
1470 @vindex LaTeX-item-regexp
1472 You can explicitely indent single lines, usually by pressing @key{TAB},
1473 or marked regions by calling @code{indent-region} on it. If you have
1474 @code{auto-fill-mode} enabled and a line is broken while you type it,
1475 Emacs automatically cares about the indentation in the following line.
1476 If you want to have a similar behavior upon typing @key{RET}, you can
1477 customize the variable @code{TeX-newline-function} and change the
1478 default of @code{newline} which does no indentation to
1479 @code{newline-and-indent} which indents the new line or
1480 @code{reindent-then-newline-and-indent} which indents both the current
1482 @vindex TeX-newline-function
1484 There are certain @LaTeX{} environments which should be indented in a
1485 special way, like @samp{tabular} or @samp{verbatim}. Those environments
1486 may be specified in the variable @code{LaTeX-indent-environment-list}
1487 together with their special indentation functions. Taking the
1488 @samp{verbatim} environment as an example you can see that
1489 @code{current-indentation} is used as the indentation function. This
1490 will stop @AUCTeX{} from doing any indentation in the environment if you
1491 hit @key{TAB} for example.
1492 @vindex LaTeX-indent-environment-list
1494 There are environments in @code{LaTeX-indent-environment-list} which do
1495 not bring a special indentation function with them. This is due to the
1496 fact that first the respective functions are not implemented yet and
1497 second that filling will be disabled for the specified environments.
1498 This shall prevent the source code from being messed up by accidently
1499 filling those environments with the standard filling routine. If you
1500 think that providing special filling routines for such environments
1501 would be an appropriate and challenging task for you, you are invited to
1502 contribute. (@xref{Filling}, for further information about the filling
1504 @vindex LaTeX-indent-environment-list
1506 The check for the indentation function may be enabled or disabled by
1507 customizing the variable @code{LaTeX-indent-environment-check}.
1508 @vindex LaTeX-indent-environment-check
1510 As a side note with regard to formatting special environments: Newer
1511 Emacsen include @file{align.el} and therefore provide some support for
1512 formatting @samp{tabular} and @samp{tabbing} environments with the
1513 function @code{align-current} which will nicely align columns in the
1516 @AUCTeX{} is able to format commented parts of your code just as any
1517 other part. This means @LaTeX{} environments and @TeX{} groups in
1518 comments will be indented syntactically correct if the variable
1519 @code{LaTeX-syntactic-comments} is set to t. If you disable it,
1520 comments will be filled like normal text and no syntactic indentation
1522 @vindex LaTeX-syntactic-comments
1524 Following you will find a list of most commands and variables related
1525 to indenting with a small summary in each case:
1530 @findex LaTeX-indent-line
1531 @code{LaTeX-indent-line} will indent the current line.
1535 @code{newline-and-indent} inserts a new line (much like @key{RET}) and
1536 moves the cursor to an appropriate position by the left margin.
1538 Most keyboards nowadays lack a linefeed key and @kbd{C-j} may be tedious
1539 to type. Therefore you can customize @AUCTeX{} to perform indentation
1540 upon typing @key{RET} as well. The respective option is called
1541 @code{TeX-newline-function}.
1548 @defopt LaTeX-indent-environment-list
1549 List of environments with special indentation. The second element in
1550 each entry is the function to calculate the indentation level in
1553 The filling code currently cannot handle tabular-like environments
1554 which will be completely messed-up if you try to format them. This is
1555 why most of these environments are included in this customization
1556 option without a special indentation function. This will prevent that
1560 @defopt LaTeX-indent-level
1561 Number of spaces to add to the indentation for each @samp{\begin} not
1562 matched by a @samp{\end}.
1565 @defopt LaTeX-item-indent
1566 Number of spaces to add to the indentation for @samp{\item}'s in list
1570 @defopt TeX-brace-indent-level
1571 Number of spaces to add to the indentation for each @samp{@{} not
1572 matched by a @samp{@}}.
1575 @defopt LaTeX-syntactic-comments
1576 If non-nil comments will be filled and indented according to @LaTeX{}
1577 syntax. Otherwise they will be filled like normal text.
1580 @defopt TeX-newline-function
1581 Used to specify the function which is called when @key{RET} is pressed.
1582 This will normally be @code{newline} which simply inserts a new line.
1583 In case you want to have @AUCTeX{} do indentation as well when you press
1584 @key{RET}, use the built-in functions @code{newline-and-indent} or
1585 @code{reindent-then-newline-and-indent}. The former inserts a new line
1586 and indents the following line, i.e. it moves the cursor to the right
1587 position and therefore acts as if you pressed @key{LFD}. The latter
1588 function additionally indents the current line. If you choose
1589 @samp{Other}, you can specify your own fancy function to be called when
1590 @key{RET} is pressed.
1598 @cindex Reformatting
1601 Filling deals with the insertion of line breaks to prevent lines from
1602 becoming wider than what is specified in @code{fill-column}. The
1603 linebreaks will be inserted automatically if @code{auto-fill-mode} is
1604 enabled. In this case the source is not only filled but also indented
1605 automatically as you write it.
1607 @code{auto-fill-mode} can be enabled for @AUCTeX{} by calling
1608 @code{turn-on-auto-fill} in one of the hooks @AUCTeX{} is running.
1609 @xref{Modes and Hooks}. As an example, if you want to enable
1610 @code{auto-fill-mode} in @code{LaTeX-mode}, put the following into your
1614 (add-hook 'LaTeX-mode-hook 'turn-on-auto-fill)
1617 You can manually fill explicitely marked regions, paragraphs,
1618 environments, complete sections, or the whole buffer. (Note that manual
1619 filling in @AUCTeX{} will indent the start of the region to be filled in
1620 contrast to many other Emacs modes.)
1622 There are some syntactical constructs which are handled specially with
1623 regard to filling. These are so-called code comments and paragraph
1626 Code comments are comments preceded by code or text in the same line.
1627 Upon filling a region, code comments themselves will not get filled.
1628 Filling is done from the start of the region to the line with the code
1629 comment and continues after it. In order to prevent overfull lines in
1630 the source code, a linebreak will be inserted before the last
1631 non-comment word by default. This can be changed by customizing
1632 @code{LaTeX-fill-break-before-code-comments}. If you have overfull
1633 lines with code comments you can fill those explicitely by calling
1634 @code{LaTeX-fill-paragraph} or pressing @kbd{M-q} with the cursor
1635 positioned on them. This will add linebreaks in the comment and indent
1636 subsequent comment lines to the column of the comment in the first line
1637 of the code comment. In this special case @kbd{M-q} only acts on the
1638 current line and not on the whole paragraph.
1640 Lines with @samp{\par} are treated similarly to code comments,
1641 i.e. @samp{\par} will be treated as paragraph boundary which should not
1642 be followed by other code or text. But it is not treated as a real
1643 paragraph boundary like an empty line where filling a paragraph would
1646 Paragraph commands like @samp{\section} or @samp{\noindent} (the list of
1647 commands is defined by @code{LaTeX-paragraph-commands}) are often to be
1648 placed in their own line(s). This means they should not be consecuted
1649 with any preceding or following adjacent lines of text. @AUCTeX{} will
1650 prevent this from happening if you do not put any text except another
1651 macro after the end of the last brace of the respective macro. If
1652 there is other text after the macro, @AUCTeX{} regards this as a sign
1653 that the macro is part of the following paragraph.
1654 @vindex LaTeX-paragraph-commands
1656 Here are some examples:
1664 \begin@{quote@}\label@{foo@}
1668 If you press @kbd{M-q} on the first line in both examples, nothing will
1669 change. But if you write
1672 \begin@{quote@} text
1676 and press @kbd{M-q}, you will get
1679 \begin@{quote@} text text text text text
1682 Besides code comments and paragraph commands, another speciality of
1683 filling in @AUCTeX{} involves commented lines. You should be aware that
1684 these comments are treated as islands in the rest of the @LaTeX{} code
1685 if syntactic filling is enabled. This means, for example, if you try to
1686 fill an environment with @code{LaTeX-fill-environment} and have the
1687 cursor placed on a commented line which does not have a surrounding
1688 environment inside the comment, @AUCTeX{} will report an error.
1689 @findex LaTeX-fill-environment
1691 The relevant commands and variables with regard to filling are:
1696 @findex LaTeX-fill-paragraph
1697 @code{LaTeX-fill-paragraph} will fill and indent the current paragraph.
1701 Alias for @kbd{C-c C-q C-p}
1705 @findex LaTeX-fill-environment
1706 @code{LaTeX-fill-environment} will fill and indent the current
1707 environment. This may e.g. be the `document' environment, in which case
1708 the entire document will be formatted.
1712 @findex LaTeX-fill-section
1713 @code{LaTeX-fill-section} will fill and indent the current logical
1718 @findex LaTeX-fill-region
1719 @code{LaTeX-fill-region} will fill and indent the current region.
1722 @defopt LaTeX-fill-break-at-separators
1723 List of separators before or after which respectively linebreaks will
1724 be inserted if they do not fit into one line. The separators can be
1725 curly braces, brackets, switches for inline math (@samp{$}, @samp{\(},
1726 @samp{\)}) and switches for display math (@samp{\[}, @samp{\]}). Such
1727 formatting can be useful to make macros and math more visible or to
1728 prevent overfull lines in the @LaTeX{} source in case a package for
1729 displaying formatted @TeX{} output inside the Emacs buffer, like
1730 preview-latex, is used.
1733 @defopt LaTeX-fill-break-before-code-comments
1734 Code comments are comments preceded by some other text in the same line.
1735 When a paragraph containing such a comment is to be filled, the comment
1736 start will be seen as a border after which no line breaks will be
1737 inserted in the same line. If the option
1738 @code{LaTeX-fill-break-before-code-comments} is enabled (which is the
1739 default) and the comment does not fit into the line, a line break will
1740 be inserted before the last non-comment word to minimize the chance that
1741 the line becomes overfull.
1745 @chapter Controlling Screen Display
1747 It is often desirable to get visual help of what markup code in a text
1748 actually does without having to decipher it explicitly. For this
1749 purpose Emacs and @AUCTeX{} provide font locking (also known as syntax
1750 highlighting) which visually sets off markup code like macros or
1751 environments by using different colors or fonts. For example text to be
1752 typeset in italics can be displayed with an italic font in the editor as
1753 well, or labels and references get their own distinct color.
1755 While font locking helps you grasp the purpose of markup code and
1756 separate markup from content, the markup code can still be distracting.
1757 @AUCTeX{} lets you hide those parts and show them again at request with
1758 its built-in support for hiding macros and environments which we call
1761 Besides folding of macros and environments, @AUCTeX{} provides support
1762 for Emacs' outline mode which lets you narrow the buffer content to
1763 certain sections of your text by hiding the parts not belonging to these
1766 Moreover, you can focus in a specific portion of the code by narrowing
1767 the buffer to the desired region. @AUCTeX{} provides also functions to
1768 narrow the buffer to the current group and to @LaTeX{} environments.
1771 * Font Locking:: Font Locking
1772 * Folding:: Folding Macros and Environments
1773 * Outline:: Outlining the Document
1774 * Narrowing:: Restricting display and editing to a portion of the buffer
1778 @section Font Locking
1779 @cindex Font Locking
1780 @cindex Syntax Highlighting
1783 Font locking is supposed to improve readability of the source code by
1784 highlighting certain keywords with different colors or fonts. It
1785 thereby lets you recognize the function of markup code to a certain
1786 extent without having to read the markup command. For general
1787 information on controlling font locking with Emacs' Font Lock mode, see
1788 @ref{Font Lock, , Font Lock Mode, emacs, GNU Emacs Manual}.
1790 @defopt TeX-install-font-lock
1791 Once font locking is enabled globally or for the major modes provided by
1792 @AUCTeX{}, the font locking patterns and functionality of @fontlatex{}
1793 are activated by default. You can switch to a different font locking
1794 scheme or disable font locking in @AUCTeX{} by customizing the variable
1795 @code{TeX-install-font-lock}.
1797 Besides @fontlatex{} @AUCTeX{} ships with a scheme which is derived
1798 from Emacs' default @LaTeX{} mode and activated by choosing
1799 @code{tex-font-setup}. Be aware that this scheme is not coupled with
1800 @AUCTeX{}'s style system and not the focus of development. Therefore
1801 and due to @fontlatex{} being much more feature-rich the following
1802 explanations will only cover @fontlatex{}.
1804 In case you want to hook in your own fontification scheme, you can
1805 choose @code{other} and insert the name of the function which sets up
1806 your font locking patterns. If you want to disable fontification in
1807 @AUCTeX{} completely, choose @code{ignore}.
1810 @fontlatex{} provides many options for customization which are
1811 accessible with @kbd{M-x customize-group RET font-latex RET}. For this
1812 description the various options are explained in conceptional groups.
1815 * Fontification of macros:: Fontification of macros
1816 * Fontification of quotes:: Fontification of quotes
1817 * Fontification of math:: Fontification of math constructs
1818 * Verbatim content:: Verbatim macros and environments
1819 * Faces:: Faces used by font-latex
1820 * Known problems:: Known fontification problems
1823 @node Fontification of macros
1824 @subsection Fontification of macros
1826 Highlighting of macros can be customized by adapting keyword lists which
1827 can be found in the customization group @code{font-latex-keywords}.
1829 Three types of macros can be handled differently with respect to
1834 Commands of the form @samp{\foo[bar]@{baz@}} which consist of the macro
1835 itself, optional arguments in square brackets and mandatory arguments in
1836 curly braces. For the command itself the face
1837 @code{font-lock-keyword-face} will be used and for the optional
1838 arguments the face @code{font-lock-variable-name-face}. The face
1839 applied to the mandatory argument depends on the macro class represented
1840 by the respective built-in variables.
1842 Declaration macros of the form @samp{@{\foo text@}} which consist of the
1843 macro which may be enclosed in a @TeX{} group together with text to be
1844 affected by the macro. In case a @TeX{} group is present, the macro
1845 will get the face @code{font-lock-keyword-face} and the text will get
1846 the face configured for the respective macro class. If no @TeX{} group
1847 is present, the latter face will be applied to the macro itself.
1849 Simple macros of the form @samp{\foo} which do not have any arguments or
1850 groupings. The respective face will be applied to the macro itself.
1853 Customization variables for @samp{\foo[bar]@{baz@}} type macros allow
1854 both the macro name and the sequence of arguments to be specified. The
1855 latter is done with a string which can contain the characters
1858 indicating the existence of a starred variant for the macro,
1860 for optional arguments in brackets,
1862 for mandatory arguments in braces,
1864 for mandatory arguments consisting of a single macro and
1866 as a prefix indicating that two alternatives are following.
1868 For example the specifier for @samp{\documentclass} would be @samp{[@{}
1869 because the macro has one optional followed by one mandatory argument.
1870 The specifier for @samp{\newcommand} would be @samp{*|@{\[[@{} because
1871 there is a starred variant, the mandatory argument following the macro
1872 name can be a macro or a @TeX{} group which can be followed by two
1873 optional arguments and the last token is a mandatory argument in braces.
1875 Customization variables for the @samp{@{\foo text@}} and @samp{\foo}
1876 types are simple lists of strings where each entry is a macro name
1877 (without the leading backslash).
1879 @subheading General macro classes
1881 @fontlatex{} provides keyword lists for different macro classes which
1882 are described in the following table:
1884 @vindex font-latex-match-function-keywords
1885 @vindex font-latex-match-reference-keywords
1886 @vindex font-latex-match-textual-keywords
1887 @vindex font-latex-match-variable-keywords
1888 @vindex font-latex-match-warning-keywords
1890 @item font-latex-match-function-keywords
1891 Keywords for macros defining or related to functions, like
1892 @samp{\newcommand}.@*
1893 Type: @samp{\macro[...]@{...@}}@*
1894 Face: @code{font-lock-function-name-face}
1896 @item font-latex-match-reference-keywords
1897 Keywords for macros defining or related to references, like
1899 Type: @samp{\macro[...]@{...@}}@*
1900 Face: @code{font-lock-constant-face}
1902 @item font-latex-match-textual-keywords
1903 Keywords for macros specifying textual content, like @samp{\caption}.@*
1904 Type: @samp{\macro[...]@{...@}}@*
1905 Face: @code{font-lock-type-face}
1907 @item font-latex-match-variable-keywords
1908 Keywords for macros defining or related to variables, like
1909 @samp{\setlength}.@*
1910 Type: @samp{\macro[...]@{...@}}@*
1911 Face: @code{font-lock-variable-name-face}
1913 @item font-latex-match-warning-keywords
1914 Keywords for important macros, e.g. affecting line or page break, like
1915 @samp{\clearpage}.@*
1916 Type: @samp{\macro}@*
1917 Face: @code{font-latex-warning-face}
1920 @subheading Sectioning commands
1921 @cindex Sectioning commands, fontification of
1923 Sectioning commands are macros like @samp{\chapter} or @samp{\section}.
1924 For these commands there are two fontification schemes which may be
1925 selected by customizing the variable @code{font-latex-fontify-sectioning}.
1927 @defopt font-latex-fontify-sectioning
1928 @c Is @vindex correct?
1929 @vindex font-latex-sectioning-0-face
1930 @vindex font-latex-sectioning-1-face
1931 @vindex font-latex-sectioning-2-face
1932 @vindex font-latex-sectioning-3-face
1933 @vindex font-latex-sectioning-4-face
1934 @vindex font-latex-sectioning-5-face
1935 Per default sectioning commands will be shown in a larger, proportional
1936 font, which corresponds to a number for this variable. The font size
1937 varies with the sectioning level, e.g. @samp{\part}
1938 (@code{font-latex-sectioning-0-face}) has a larger font than
1939 @samp{\paragraph} (@code{font-latex-sectioning-5-face}). Typically,
1940 values from 1.05 to 1.3 for @code{font-latex-fontify-sectioning} give
1941 best results, depending on your font setup. If you rather like to use
1942 the base font and a different color, set the variable to the symbol
1943 @samp{color}. In this case the face @code{font-lock-type-face} will be
1944 used to fontify the argument of the sectioning commands.
1947 @vindex font-latex-match-sectioning-0-keywords
1948 @vindex font-latex-match-sectioning-1-keywords
1949 @vindex font-latex-match-sectioning-2-keywords
1950 @vindex font-latex-match-sectioning-3-keywords
1951 @vindex font-latex-match-sectioning-4-keywords
1952 @vindex font-latex-match-sectioning-5-keywords
1953 You can make @fontlatex{} aware of your own sectioning commands be
1954 adding them to the keyword lists:
1955 @code{font-latex-match-sectioning-0-keywords}
1956 (@code{font-latex-sectioning-0-face}) @dots{}
1957 @code{font-latex-match-sectioning-5-keywords}
1958 (@code{font-latex-sectioning-5-face}).
1960 @vindex font-latex-slide-title-face
1961 @vindex font-latex-match-slide-title-keywords
1962 Related to sectioning there is special support for slide titles which
1963 may be fontified with the face @code{font-latex-slide-title-face}. You
1964 can add macros which should appear in this face by customizing the
1965 variable @code{font-latex-match-slide-title-keywords}.
1967 @subheading Commands for changing fonts
1969 @LaTeX{} provides various macros for changing fonts or font attributes.
1970 For example, you can select an italic font with @samp{\textit@{...@}} or
1971 bold with @samp{\textbf@{...@}}. An alternative way to specify these
1972 fonts is to use special macros in @TeX{} groups, like @samp{@{\itshape
1973 ...@}} for italics and @samp{@{\bfseries ...@}} for bold. As mentioned
1974 above, we call the former variants commands and the latter
1977 Besides the macros for changing fonts provided by @LaTeX{} there is an
1978 infinite number of other macros---either defined by yourself for logical
1979 markup or defined by macro packages---which affect the font in the
1980 typeset text. While @LaTeX{}'s built-in macros and macros of packages
1981 known by @AUCTeX{} are already handled by @fontlatex{}, different
1982 keyword lists per type style and macro type are provided for entering
1983 your own macros which are listed in the table below.
1985 @vindex font-latex-match-bold-command-keywords
1986 @vindex font-latex-match-italic-command-keywords
1987 @vindex font-latex-match-math-command-keywords
1988 @vindex font-latex-match-type-command-keywords
1989 @vindex font-latex-match-bold-declaration-keywords
1990 @vindex font-latex-match-italic-declaration-keywords
1991 @vindex font-latex-match-type-declaration-keywords
1993 @item font-latex-match-bold-command-keywords
1994 Keywords for commands specifying a bold type style.@*
1995 Face: @code{font-latex-bold-face}
1996 @item font-latex-match-italic-command-keywords
1997 Keywords for commands specifying an italic font.@*
1998 Face: @code{font-latex-italic-face}
1999 @item font-latex-match-math-command-keywords
2000 Keywords for commands specifying a math font.@*
2001 Face: @code{font-latex-math-face}
2002 @item font-latex-match-type-command-keywords
2003 Keywords for commands specifying a typewriter font.@*
2004 Face: @code{font-lock-type-face}
2005 @item font-latex-match-bold-declaration-keywords
2006 Keywords for declarations specifying a bold type style.@*
2007 Face: @code{font-latex-bold-face}
2008 @item font-latex-match-italic-declaration-keywords
2009 Keywords for declarations specifying an italic font.@*
2010 Face: @code{font-latex-italic-face}
2011 @item font-latex-match-type-declaration-keywords
2012 Keywords for declarations specifying a typewriter font.@*
2013 Face: @code{font-latex-type-face}
2016 @subheading Deactivating defaults of built-in keyword classes
2018 @vindex font-latex-deactivated-keyword-classes
2019 @fontlatex{} ships with predefined lists of keywords for the classes
2020 described above. You can disable these defaults per class by
2021 customizing the variable @code{font-latex-deactivated-keyword-classes}.
2022 This is a list of strings for keyword classes to be deactivated. Valid
2023 entries are "warning", "variable", "reference", "function" ,
2024 "sectioning-0", "sectioning-1", "sectioning-2", "sectioning-3",
2025 "sectioning-4", "sectioning-5", "textual", "bold-command",
2026 "italic-command", "math-command", "type-command", "bold-declaration",
2027 "italic-declaration", "type-declaration".
2029 You can also get rid of certain keywords only. For example if you want
2030 to remove highlighting of footnotes as references you can put the
2031 following stanza into your init file:
2034 (eval-after-load "font-latex"
2036 font-latex-match-reference-keywords-local
2037 (remove "footnote" font-latex-match-reference-keywords-local)))
2040 But note that this means fiddling with @fontlatex{}'s internals and is
2041 not guaranteed to work in future versions of @fontlatex{}.
2043 @subheading User-defined keyword classes
2045 In case the customization options explained above do not suffice for
2046 your needs, you can specify your own keyword classes by customizing the
2047 variable @code{font-latex-user-keyword-classes}.
2049 @defopt font-latex-user-keyword-classes
2050 Every keyword class consists of four parts, a name, a list of keywords,
2051 a face and a specifier for the type of macros to be highlighted.
2053 When adding new entries, you have to use unique values for the class
2054 names, i.e. they must not clash with names of the built-in keyword
2055 classes or other names given by you. Additionally the names must not
2058 The list of keywords defines which commands and declarations should be
2059 covered by the keyword class. A keyword can either be a simple command
2060 name omitting the leading backslash or a list consisting of the command
2061 name and a string specifying the sequence of arguments for the command.
2063 The face argument can either be an existing face or font specifications
2064 made by you. (The latter option is not available on XEmacs.)
2066 There are three alternatives for the type of keywords---``Command with
2067 arguments'', ``Declaration inside @TeX{} group'' and ``Command without
2068 arguments''---which correspond with the macro types explained above.
2071 @node Fontification of quotes
2072 @subsection Fontification of quotes
2073 @cindex Quotes, fontification of
2075 Text in quotation marks is displayed with the face
2076 @code{font-latex-string-face}. Besides the various forms of opening and
2077 closing double and single quotation marks, so-called guillemets (<<, >>)
2078 can be used for quoting. Because there are two styles of using
2079 them---French style: << text >>; German style: >>text<<---you can
2080 customize the variable @code{font-latex-quotes} to tell @fontlatex{}
2081 which type you are using if the correct value cannot be derived from
2082 document properties.
2084 @defopt font-latex-quotes
2085 The default value of @code{font-latex-quotes} is @samp{auto} which means
2086 that @fontlatex{} will try to derive the correct type of quotation mark
2087 matching from document properties like the language option supplied to
2088 the babel @LaTeX{} package.
2090 If the automatic detection fails for you and you mostly use one specific
2091 style you can set it to a specific language-dependent value as well.
2092 Set the value to @samp{german} if you are using >>German quotes<< and to
2093 @samp{french} if you are using << French quotes >>. @fontlatex{} will
2094 recognize the different ways these quotes can be given in your source
2095 code, i.e. (@samp{"<}, @samp{">}), (@samp{<<}, @samp{>>}) and the
2096 respective 8-bit variants.
2098 If you set @code{font-latex-quotes} to nil, quoted content will not be
2103 @node Fontification of math
2104 @subsection Fontification of mathematical constructs
2105 @cindex Math, fontification of
2106 @cindex Subscript, fontification of
2107 @cindex Superscript, fontification of
2109 @vindex font-latex-match-math-command-keywords
2110 @vindex font-latex-math-environments
2111 In @LaTeX{} mathematics can be indicated by a variety of different
2112 methods: toggles (like dollar signs), macros and environments. Math
2113 constructs known by @fontlatex{} are displayed with the face
2114 @code{font-latex-math-face}. Support for dollar signs and shorthands
2115 like @samp{\(...\)} or @samp{\[...\]} is built-in and not customizable.
2116 Support for other math macros and environments can be adapted by
2117 customizing the variables @code{font-latex-match-math-command-keywords}
2118 and @code{font-latex-math-environments} respectively.
2120 In order to make math constructs more readable, @fontlatex{} displays
2121 subscript and superscript parts in a smaller font and raised or lowered
2122 respectively. This fontification feature can be controlled with the
2123 variables @code{font-latex-fontify-script} and
2124 @code{font-latex-script-display}.
2126 @defopt font-latex-fontify-script
2127 If non-nil, fontify subscript and superscript strings.
2129 Note that this feature is not available on XEmacs, for which it is
2130 disabled per default. In GNU Emacs raising and lowering is not enabled
2131 for versions 21.3 and before due to it working not properly.
2134 @defopt font-latex-script-display
2135 Display specification for subscript and superscript content. The car is
2136 used for subscript, the cdr is used for superscript. The feature is
2137 implemented using so-called display properties. For information on what
2138 exactly to specify for the values, see @ref{Other Display Specs, , Other
2139 Display Specifications, elisp, GNU Emacs Lisp Reference Manual}.
2142 @node Verbatim content
2143 @subsection Verbatim macros and environments
2144 @cindex Verbatim, fontification of
2146 Usually it is not desirable to have content to be typeset verbatim
2147 highlighted according to @LaTeX{} syntax. Therefore this content will
2148 be fontified uniformly with the face @code{font-latex-verbatim-face}.
2150 @vindex LaTeX-verbatim-macros-with-delims
2151 @vindex LaTeX-verbatim-macros-with-braces
2152 @vindex LaTeX-verbatim-environments
2153 @fontlatex{} differentiates three different types of verbatim
2154 constructs for fontification. Macros with special characters like | as
2155 delimiters, macros with braces, and environments. Which macros and
2156 environments are recognized is controlled by the variables
2157 @code{LaTeX-verbatim-macros-with-delims},
2158 @code{LaTeX-verbatim-macros-with-braces}, and
2159 @code{LaTeX-verbatim-environments} respectively.
2162 @subsection Faces used by @fontlatex{}
2165 In case you want to change the colors and fonts used by @fontlatex{}
2166 please refer to the faces mentioned in the explanations above and use
2167 @kbd{M-x customize-face RET <face> RET}. All faces defined by
2168 @fontlatex{} are accessible through a customization group by typing
2169 @kbd{M-x customize-group RET font-latex-highlighting-faces RET}.
2171 @node Known problems
2172 @subsection Known fontification problems
2173 @cindex Dollar signs, color bleed with
2174 @cindex Math, fontification problems with
2176 In certain cases the fontification machinery fails to interpret buffer
2177 contents correctly. This can lead to color bleed, i.e. large parts of a
2178 buffer get fontified with an inappropriate face. A typical situation
2179 for this to happen is the use of a dollar sign (@samp{$}) in a verbatim
2180 macro or environment. If @fontlatex{} is not aware of the verbatim
2181 construct, it assumes the dollar sign to be a toggle for mathematics and
2182 fontifies the following buffer content with the respective face until it
2183 finds a closing dollar sign or till the end of the buffer.
2185 As a remedy you can make the verbatim construct known to @fontlatex{},
2186 @pxref{Verbatim content}. If this is not possible, you can insert a
2187 commented dollar sign (@samp{%$}) at the next suitable end of line as a
2189 @c As a last resort one can set `font-lock-keywords-only', but we should
2190 @c probably not advise users to do this.
2194 @section Folding Macros and Environments
2201 A popular complaint about markup languages like @TeX{} and @LaTeX{} is
2202 that there is too much clutter in the source text and that one cannot
2203 focus well on the content. There are macros where you are only
2204 interested in the content they are enclosing, like font specifiers where
2205 the content might already be fontified in a special way by font locking.
2206 Or macros the content of which you only want to see when actually
2207 editing it, like footnotes or citations. Similarly you might find
2208 certain environments or comments distracting when trying to concentrate
2209 on the body of your document.
2211 With @AUCTeX{}'s folding functionality you can collapse those items and
2212 replace them by a fixed string, the content of one of their arguments,
2213 or a mixture of both. If you want to make the original text visible
2214 again in order to view or edit it, move point sideways onto the
2215 placeholder (also called display string) or left-click with the mouse
2216 pointer on it. (The latter is currently only supported on Emacs.) The
2217 macro or environment will unfold automatically, stay open as long as
2218 point is inside of it and collapse again once you move point out of it.
2219 (Note that folding of environments currently does not work in every
2222 In order to use this feature, you have to activate @code{TeX-fold-mode}
2223 which will activate the auto-reveal feature and the necessary commands
2224 to hide and show macros and environments. You can activate the mode in
2225 a certain buffer by typing the command @kbd{M-x TeX-fold-mode RET} or
2226 using the keyboard shortcut @kbd{C-c C-o C-f}. If you want to use it
2227 every time you edit a @LaTeX{} document, add it to a hook:
2228 @findex TeX-fold-mode
2232 (add-hook 'LaTeX-mode-hook (lambda ()
2236 If it should be activated in all @AUCTeX{} modes, use
2237 @code{TeX-mode-hook} instead of @code{LaTeX-mode-hook}.
2239 Once the mode is active there are several commands available to hide
2240 and show macros, environments and comments:
2242 @deffn Command TeX-fold-buffer
2244 (@kbd{C-c C-o C-b}) Hide all foldable items in the current buffer
2245 according to the setting of @code{TeX-fold-type-list}.
2247 If you want to have this done automatically every time you open a file,
2248 add it to a hook and make sure the function is called after font locking
2249 is set up for the buffer. The following code should accomplish this:
2252 (add-hook 'find-file-hook 'TeX-fold-buffer t)
2255 The command can be used any time to refresh the whole buffer and fold
2256 any new macros and environments which were inserted after the last
2257 invocation of the command.
2260 @defopt TeX-fold-type-list
2261 List of symbols determining the item classes to consider for folding.
2262 This can be macros, environments and comments. Per default only macros
2263 and environments are folded.
2266 @defopt TeX-fold-force-fontify
2267 In order for all folded content to get the right faces, the whole buffer
2268 has to be fontified before folding is carried out.
2269 @code{TeX-fold-buffer} therefore will force fontification of unfontified
2270 regions. As this will prolong the time folding takes, you can prevent
2271 forced fontification by customizing the variable
2272 @code{TeX-fold-force-fontify}.
2275 @defopt TeX-fold-auto
2276 By default, a macro inserted with @code{TeX-insert-macro} (@kbd{C-c
2277 C-m}) will not be folded. Set this variable to a non-nil value to
2278 aumatically fold macros as soon as they are inserted.
2281 @defopt TeX-fold-preserve-comments
2282 By default items found in comments will be folded. If your comments
2283 often contain unfinished code this might lead to problems. Give this
2284 variable a non-nil value and foldable items in your comments will be
2288 @defopt TeX-fold-unfold-around-mark
2289 When this variable is non-nil and there is an active regione, text
2290 around the mark will be kept unfolded.
2293 @deffn Command TeX-fold-region
2295 (@kbd{C-c C-o C-r}) Hide all configured macros in the marked region.
2298 @deffn Command TeX-fold-paragraph
2300 (@kbd{C-c C-o C-p}) Hide all configured macros in the paragraph
2304 @deffn Command TeX-fold-macro
2306 (@kbd{C-c C-o C-m}) Hide the macro on which point currently is located.
2307 If the name of the macro is found in @code{TeX-fold-macro-spec-list},
2308 the respective display string will be shown instead. If it is not
2309 found, the name of the macro in sqare brackets or the default string for
2310 unspecified macros (@code{TeX-fold-unspec-macro-display-string}) will be
2311 shown, depending on the value of the variable
2312 @code{TeX-fold-unspec-use-name}.
2315 @deffn Command TeX-fold-env
2317 (@kbd{C-c C-o C-e}) Hide the environment on which point currently is
2318 located. The behavior regarding the display string is analogous to
2319 @code{TeX-fold-macro} and determined by the variables
2320 @code{TeX-fold-env-spec-list} and
2321 @code{TeX-fold-unspec-env-display-string} respectively.
2324 @deffn Command TeX-fold-math
2325 Hide the math macro on which point currently is located. If the name of
2326 the macro is found in @code{TeX-fold-math-spec-list}, the respective
2327 display string will be shown instead. If it is not found, the name of
2328 the macro in sqare brackets or the default string for unspecified macros
2329 (@code{TeX-fold-unspec-macro-display-string}) will be shown, depending
2330 on the value of the variable @code{TeX-fold-unspec-use-name}.
2333 @deffn Command TeX-fold-comment
2335 (@kbd{C-c C-o C-c}) Hide the comment point is located on.
2338 @deffn Command TeX-fold-clearout-buffer
2340 (@kbd{C-c C-o b}) Permanently unfold all macros and environments in the
2344 @deffn Command TeX-fold-clearout-region
2346 (@kbd{C-c C-o r}) Permanently unfold all macros and environments in the
2350 @deffn Command TeX-fold-clearout-paragraph
2352 (@kbd{C-c C-o p}) Permanently unfold all macros and environments in the
2353 paragraph containing point.
2356 @deffn Command TeX-fold-clearout-item
2358 (@kbd{C-c C-o i}) Permanently show the macro or environment on which
2359 point currently is located. In contrast to temporarily opening the
2360 macro when point is moved sideways onto it, the macro will be
2361 permanently unfolded and will not collapse again once point is leaving
2365 @deffn Command TeX-fold-dwim
2367 (@kbd{C-c C-o C-o}) Hide or show items according to the current context.
2368 If there is folded content, unfold it. If there is a marked region,
2369 fold all configured content in this region. If there is no folded
2370 content but a macro or environment, fold it.
2373 @vindex TeX-fold-command-prefix
2374 In case you want to use a different prefix than @kbd{C-c C-o} for these
2375 commands you can customize the variable @code{TeX-fold-command-prefix}.
2376 (Note that this will not change the key binding for activating the
2379 The commands above will only take macros or environments into
2380 consideration which are specified in the variables
2381 @code{TeX-fold-macro-spec-list} or @code{TeX-fold-env-spec-list}
2384 @defopt TeX-fold-macro-spec-list
2385 List of replacement specifiers and macros to fold. The specifier can be
2386 a string, an integer or a function symbol.
2388 If you specify a string, it will be used as a display replacement for
2389 the whole macro. Numbers in braces, brackets, parens or angle brackets
2390 will be replaced by the respective macro argument. For example
2391 @samp{@{1@}} will be replaced by the first mandatory argument of the
2392 macro. One can also define alternatives within the specifier which are
2393 used if an argument is not found. Alternatives are separated by
2394 @samp{||}. They are most useful with optional arguments. As an
2395 example, the default specifier for @samp{\item} is @samp{[1]:||*} which
2396 means that if there is an optional argument, its value is shown followed
2397 by a colon. If there is no optional argument, only an asterisk is used
2398 as the display string.
2400 If you specify a number as the first element, the content of the
2401 respective mandatory argument of a @LaTeX{} macro will be used as the
2404 If the first element is a function symbol, the function will be called
2405 with all mandatory arguments of the macro and the result of the function
2406 call will be used as a replacement for the macro.
2408 The placeholder is made by copying the text from the buffer together with
2409 its properties, i.e. its face as well. If fontification has not
2410 happened when this is done (e.g. because of lazy font locking) the
2411 intended fontification will not show up. As a workaround you can leave
2412 Emacs idle a few seconds and wait for stealth font locking to finish
2413 before you fold the buffer. Or you just re-fold the buffer with
2414 @code{TeX-fold-buffer} when you notice a wrong fontification.
2417 @defopt TeX-fold-env-spec-list
2418 List of display strings or argument numbers and environments to fold.
2419 Argument numbers refer to the @samp{\begin} statement. That means if
2420 you have e.g. @samp{\begin@{tabularx@}@{\linewidth@}@{XXX@} ...
2421 \end@{tabularx@}} and specify 3 as the argument number, the resulting
2422 display string will be ``XXX''.
2425 @defopt TeX-fold-math-spec-list
2426 List of display strings and math macros to fold.
2429 @vindex LaTeX-fold-macro-spec-list
2430 @vindex LaTeX-fold-env-spec-list
2431 @vindex LaTeX-fold-math-spec-list
2432 The variables @code{TeX-fold-macro-spec-list},
2433 @code{TeX-fold-env-spec-list}, and @code{TeX-fold-math-spec-list} apply
2434 to any @AUCTeX{} mode. If you want to make settings which are only
2435 applied to @LaTeX{} mode, you can use the mode-specific variables
2436 @code{LaTeX-fold-macro-spec-list}, @code{LaTeX-fold-env-spec-list}, and
2437 @code{LaTeX-fold-math-spec-list}
2439 @defopt TeX-fold-unspec-macro-display-string
2440 Default display string for macros which are not specified in
2441 @code{TeX-fold-macro-spec-list}.
2444 @defopt TeX-fold-unspec-env-display-string
2445 Default display string for environments which are not specified in
2446 @code{TeX-fold-env-spec-list}.
2449 @defopt TeX-fold-unspec-use-name
2450 If non-nil the name of the macro or environment surrounded by square
2451 brackets is used as display string, otherwise the defaults specified in
2452 @code{TeX-fold-unspec-macro-display-string} or
2453 @code{TeX-fold-unspec-env-display-string} respectively.
2456 When you hover with the mouse pointer over folded content, its original
2457 text will be shown in a tooltip or the echo area depending on Tooltip
2458 mode being activate. In order to avoid exorbitantly big tooltips and to
2459 cater for the limited space in the echo area the content will be cropped
2460 after a certain amount of characters defined by the variable
2461 @code{TeX-fold-help-echo-max-length}.
2463 @defopt TeX-fold-help-echo-max-length
2464 Maximum length of original text displayed in a tooltip or the echo area
2465 for folded content. Set it to zero in order to disable this feature.
2470 @section Outlining the Document
2477 @AUCTeX{} supports the standard outline minor mode using
2478 @LaTeX{}/@ConTeXt{} sectioning commands as header lines. @xref{Outline
2479 Mode, , Outline Mode, emacs, GNU Emacs Manual}.
2481 You can add your own headings by setting the variable
2482 @code{TeX-outline-extra}.
2484 @defvar TeX-outline-extra
2485 List of extra @TeX{} outline levels.
2487 Each element is a list with two entries. The first entry is the regular
2488 expression matching a header, and the second is the level of the header.
2489 A @samp{^} is automatically prepended to the regular expressions in the
2490 list, so they must match text at the beginning of the line.
2492 See @code{LaTeX-section-list} or @code{ConTeXt-INTERFACE-section-list}
2493 for existing header levels.
2496 The following example add @samp{\item} and @samp{\bibliography} headers,
2497 with @samp{\bibliography} at the same outline level as @samp{\section},
2498 and @samp{\item} being below @samp{\subparagraph}.
2501 (setq TeX-outline-extra
2502 '(("[ \t]*\\\\\\(bib\\)?item\\b" 7)
2503 ("\\\\bibliography\\b" 2)))
2506 You may want to check out the unbundled @file{out-xtra} package for even
2507 better outline support. It is available from your favorite emacs lisp
2513 Sometimes you want to focus your attention to a limited region of the
2514 code. You can do that by restricting the text addressable by editing
2515 commands and hiding the rest of the buffer with the narrowing functions,
2516 @pxref{Narrowing,,,emacs,GNU Emacs Manual}. In addition, AUCTeX
2517 provides a couple of other commands to narrow the buffer to a group,
2518 i.e. a region enclosed in a pair of curly braces, and to @LaTeX{}
2521 @deffn Command TeX-narrow-to-group
2523 (@kbd{C-x n g}) Make text outside current group invisible.
2526 @deffn Command LaTeX-narrow-to-environment @var{count}
2528 (@kbd{C-x n e}) Make text outside current environment invisible. With
2529 optional argument @var{count} keep visible that number of enclosing
2533 Like other standard narrowing functions, the above commands are
2534 disabled. Attempting to use them asks for confirmation and gives you
2535 the option of enabling them; if you enable the commands, confirmation
2536 will no longer be required for them.
2539 @chapter Starting Processors, Viewers and Other Programs
2541 The most powerful features of @AUCTeX{} may be those allowing you to run
2542 @TeX{}, @LaTeX{}, @ConTeXt{} and other external commands like Bib@TeX{}
2543 and @code{makeindex} from within Emacs, viewing and printing the
2544 results, and moreover allowing you to @emph{debug} your documents.
2546 @cindex tool bar, toolbar
2547 @vindex LaTeX-enable-toolbar
2548 @vindex plain-TeX-enable-toolbar
2549 @AUCTeX{} comes with a special tool bar for @TeX{} and @LaTeX{} which
2550 provides buttons for the most important commands. You can enable or
2551 disable it by customizing the options @code{plain-TeX-enable-toolbar}
2552 and @code{LaTeX-enable-toolbar} in the @code{TeX-tool-bar} customization
2556 * Commands:: Invoking external commands.
2557 * Viewing:: Invoking external viewers.
2558 * Debugging:: Debugging @TeX{} and @LaTeX{} output.
2559 * Checking:: Checking the document.
2560 * Control:: Controlling the processes.
2561 * Cleaning:: Cleaning intermediate and output files.
2562 * Documentation:: Documentation about macros and packages.
2566 @section Executing Commands
2568 @cindex Running @LaTeX{}
2569 @cindex Running @TeX{}
2572 @cindex Running commands
2573 @cindex Default command
2576 @cindex Setting the header
2577 @cindex Setting the trailer
2580 @cindex Setting the default command
2582 @cindex External Commands
2584 @cindex Making an index
2585 @cindex Running @code{makeindex}
2586 @cindex @code{makeindex}
2588 @cindex Bibliography
2590 @cindex Running Bib@TeX{}
2591 @cindex Making a bibliography
2593 @cindex Writing to a printer
2595 Formatting the document with @TeX{}, @LaTeX{} or @ConTeXt{}, viewing
2596 with a previewer, printing the document, running Bib@TeX{}, making an
2597 index, or checking the document with @command{lacheck} or
2598 @command{chktex} all require running an external command.
2601 * Starting a Command:: Starting a Command on a Document or Region
2602 * Selecting a Command:: Selecting and Executing a Command
2603 * Processor Options:: Options for @TeX{} Processors
2606 @node Starting a Command
2607 @subsection Starting a Command on a Document or Region
2609 There are two ways to run an external command, you can either run it on
2610 the current document with @code{TeX-command-master}, or on the current
2611 region with @code{TeX-command-region}. A special case of running @TeX{}
2612 on a region is @code{TeX-command-buffer} which differs from
2613 @code{TeX-command-master} if the current buffer is not its own master
2616 @deffn Command TeX-command-master
2618 (@kbd{C-c C-c}) Query the user for a command, and run it on the master
2619 file associated with the current buffer. The name of the master file is
2620 controlled by the variable @code{TeX-master}. The available commands are
2621 controlled by the variable @code{TeX-command-list}.
2623 @vindex TeX-command-list
2626 @deffn Command TeX-command-region
2628 (@kbd{C-c C-r}) Query the user for a command, and run it on the contents
2629 of the selected region. The region contents are written into the region
2630 file, after extracting the header and trailer from the master file. If
2631 mark is inactive (which can happen with Transient Mark mode), use the
2632 old region. See also the command @code{TeX-pin-region} about how to fix
2635 The name of the region file is controlled by the variable
2636 @code{TeX-region}. The name of the master file is controlled by the
2637 variable @code{TeX-master}. The header is all text up to the line
2638 matching the regular expression @code{TeX-header-end}. The trailer is
2639 all text from the line matching the regular expression
2640 @code{TeX-trailer-start}. The available commands are controlled by the
2641 variable @code{TeX-command-list}.
2643 @vindex TeX-header-end
2644 @vindex TeX-trailer-start
2646 @vindex TeX-command-list
2649 @deffn Command TeX-command-buffer
2651 (@kbd{C-c C-b}) Query the user for a command, and apply it to the
2652 contents of the current buffer. The buffer contents are written into
2653 the region file, after extracting the header and trailer from the master
2654 file. The command is then actually run on the region file. See above
2659 The name of the file for temporarily storing the text when formatting
2663 @defopt TeX-header-end
2664 A regular expression matching the end of the header. By default, this
2665 is @samp{\begin@{document@}} in @LaTeX{} mode and @samp{%**end of
2666 header} in @TeX{} mode.
2669 @defopt TeX-trailer-start
2670 A regular expression matching the start of the trailer. By default,
2671 this is @samp{\end@{document@}} in @LaTeX{} mode and @samp{\bye} in
2675 If you want to change the values of @code{TeX-header-end} and
2676 @code{TeX-trailer-start} you can do this for all files by setting the
2677 variables in a mode hook or per file by specifying them as file
2678 variables (@pxref{File Variables,,,emacs,The Emacs Editor}).
2680 @deffn Command TeX-pin-region
2682 (@kbd{C-c C-t C-r}) If you don't have a mode like Transient Mark mode
2683 active, where marks get disabled automatically, the region would need to
2684 get properly set before each call to @code{TeX-command-region}. If you
2685 fix the current region with @kbd{C-c C-t C-r}, then it will get used for
2686 more commands even though mark and point may change. An explicitly
2687 activated mark, however, will always define a new region when calling
2688 @code{TeX-command-region}.
2691 @AUCTeX{} will allow one process for each document, plus one process
2692 for the region file to be active at the same time. Thus, if you are
2693 editing @var{n} different documents, you can have @var{n} plus one
2694 processes running at the same time. If the last process you started was
2695 on the region, the commands described in @ref{Debugging} and
2696 @ref{Control} will work on that process, otherwise they will work on the
2697 process associated with the current document.
2699 @node Selecting a Command
2700 @subsection Selecting and Executing a Command
2702 Once you started the command selection with @kbd{C-c C-c}, @kbd{C-c C-s}
2703 or @kbd{C-c C-b} you will be prompted for the type of command.
2704 @AUCTeX{} will try to guess which command is appropriate in the given
2705 situation and propose it as default. Usually this is a processor like
2706 @samp{TeX} or @samp{LaTeX} if the document was changed or a viewer if
2707 the document was just typeset. Other commands can be selected in the
2708 minibuffer with completion support by typing @key{TAB}.
2710 @vindex TeX-command-list
2711 @vindex TeX-expand-list
2712 The available commands are defined by the variable
2713 @code{TeX-command-list}. Per default it includes commands for
2714 typesetting the document (e.g. @samp{LaTeX}), for viewing the output
2715 (@samp{View}), for printing (@samp{Print}), for generating an index
2716 (@samp{Index}) or for spell checking (@samp{Spell}) to name but a few.
2717 You can also add your own commands by adding entries to
2718 @code{TeX-command-list}. Refer to its doc string for information about
2719 its syntax. You might also want to look at @code{TeX-expand-list} to
2720 learn about the expanders you can use in @code{TeX-command-list}.
2722 Note that the default of the variable occasionally changes. Therefore
2723 it is advisable to add to the list rather than overwriting it. You can
2724 do this with a call to @code{add-to-list} in your init file. For
2725 example, if you wanted to add a command for running a program called
2726 @samp{foo} on the master or region file, you could do this with the
2730 (eval-after-load "tex"
2731 '(add-to-list 'TeX-command-list
2732 '("Foo" "foo %s" TeX-run-command t t :help "Run foo") t))
2735 As mentioned before, @AUCTeX{} will try to guess what command you want
2736 to invoke. If you want to use another command than @samp{TeX},
2737 @samp{LaTeX} or whatever processor @AUCTeX{} thinks is appropriate for
2738 the current mode, set the variable @code{TeX-command-default}. You can
2739 do this for all files by setting it in a mode hook or per file by
2740 specifying it as a file variable (@pxref{File Variables,,,emacs,The
2743 @defopt TeX-command-default
2744 The default command to run in this buffer. Must be an entry in
2745 @code{TeX-command-list}.
2750 In case you use biblatex in a document, when automatic parsing is
2751 enabled @AUCTeX{} checks the value of @samp{backend} option given to
2752 biblatex at load time to decide whether to use Bib@TeX{} or Biber for
2753 bibliography processing. Should @AUCTeX{} fail to detect the right
2754 backend, you can use the file local @code{LaTeX-biblatex-use-Biber}
2756 @defvr Variable LaTeX-biblatex-use-Biber
2757 If this boolean variable is set as file local, it tells to @AUCTeX{}
2758 whether to use Biber with biblatex. In this case, the autodetection of
2759 the biblatex backend will be overridden. You may want to set locally
2760 this variable if automatic parsing is not enabled.
2763 After confirming a command to execute, @AUCTeX{} will try to save any
2764 buffers related to the document, and check if the document needs to be
2765 reformatted. If the variable @code{TeX-save-query} is non-nil,
2766 @AUCTeX{} will query before saving each file. By default @AUCTeX{} will
2767 check emacs buffers associated with files in the current directory, in
2768 one of the @code{TeX-macro-private} directories, and in the
2769 @code{TeX-macro-global} directories. You can change this by setting the
2770 variable @code{TeX-check-path}.
2772 @defopt TeX-check-path
2773 Directory path to search for dependencies.
2775 If nil, just check the current file.
2776 Used when checking if any files have changed.
2779 @node Processor Options
2780 @subsection Options for @TeX{} Processors
2782 There are some options you can customize affecting which processors are
2783 invoked or the way this is done and which output they produce as a
2784 result. These options control if @acronym{DVI} or @acronym{PDF} output
2785 should be produced, if @TeX{} should be started in interactive or
2786 nonstop mode, if source specials or a Sync@TeX{} file should be produced
2787 for making inverse and forward search possible or which @TeX{} engine
2788 should be used instead of regular @TeX{}, like PDF@TeX{}, Omega or
2791 @deffn Command TeX-PDF-mode
2793 @vindex TeX-PDF-mode
2796 This command toggles the @acronym{PDF} mode of @AUCTeX{}, a buffer-local
2797 minor mode which is enabled by default. You can customize
2798 @code{TeX-PDF-mode} to give it a different default or set it as a file
2799 local variable on a per-document basis. This option usually results in
2800 calling either PDF@TeX{} or ordinary @TeX{}.
2803 @defopt TeX-DVI-via-PDFTeX
2804 If this is set, @acronym{DVI} will also be produced by calling
2805 PDF@TeX{}, setting @code{\pdfoutput=0}. This makes it possible to use
2806 PDF@TeX{} features like character protrusion even when producing
2807 @acronym{DVI} files. Contemporary @TeX{} distributions do this anyway,
2808 so that you need not enable the option within @AUCTeX{}.
2811 @deffn Command TeX-interactive-mode
2813 @vindex TeX-interactive-mode
2814 (@kbd{C-c C-t C-i}) This command toggles the interactive mode of
2815 @AUCTeX{}, a global minor mode. You can customize
2816 @code{TeX-interactive-mode} to give it a different default. In
2817 interactive mode, @TeX{} will pause with an error prompt when errors are
2818 encountered and wait for the user to type something.
2821 @cindex I/O correlation
2823 @cindex Source specials
2825 @deffn Command TeX-source-correlate-mode
2827 @vindex TeX-source-correlate-mode
2828 (@kbd{C-c C-t C-s}) Toggles support for forward and inverse search.
2829 Forward search refers to jumping to the place in the previewed document
2830 corresponding to where point is located in the document source and
2831 inverse search to the other way round. @xref{I/O Correlation}.
2833 You can permanently activate @code{TeX-source-correlate-mode} by
2834 customizing the variable @code{TeX-source-correlate-mode}. There is a
2835 bunch of customization options for the mode, use @kbd{M-x
2836 customize-group @key{RET} TeX-view @key{RET}} to find out more.
2838 @vindex TeX-source-correlate-method
2839 @AUCTeX{} is aware of three different means to do I/O correlation:
2840 source specials (only DVI output), the pdfsync @LaTeX{} package (only
2841 PDF output) and Sync@TeX{}. The choice between source specials and
2842 Sync@TeX{} can be controlled with the variable
2843 @code{TeX-source-correlate-method}.
2845 Should you use source specials it has to be stressed @emph{very}
2846 strongly however, that source specials can cause differences in page
2847 breaks and spacing, can seriously interfere with various packages and
2848 should thus @emph{never} be used for the final version of a document.
2849 In particular, fine-tuning the page breaks should be done with source
2850 specials switched off.
2853 @AUCTeX{} also allows you to easily select different @TeX{} engines for
2854 processing, either by using the entries in the @samp{TeXing Options}
2855 submenu below the @samp{Command} menu or by calling the function
2856 @code{TeX-engine-set}. These eventually set the variable
2857 @code{TeX-engine} which you can also modify directly.
2860 This variable allows you to choose which @TeX{} engine should be used
2861 for typesetting the document, i.e. the executables which will be used
2862 when you invoke the @samp{TeX} or @samp{LaTeX} commands. The value
2863 should be one of the symbols defined in @code{TeX-engine-alist-builtin}
2864 or @code{TeX-engine-alist}. The symbols @samp{default}, @samp{xetex},
2865 @samp{luatex} and @samp{omega} are available from the built-in list.
2868 Note that @code{TeX-engine} is buffer-local, so setting the variable
2869 directly or via the above mentioned menu or function will not take
2870 effect in other buffers. If you want to activate an engine for all
2871 @AUCTeX{} modes, set @code{TeX-engine} in your init file, e.g. by using
2872 @kbd{M-x customize-variable <RET>}. If you want to activate it for a
2873 certain @AUCTeX{} mode only, set the variable in the respective mode
2874 hook. If you want to activate it for certain files, set it through file
2875 variables (@pxref{File Variables,,,emacs,The Emacs Editor}).
2878 @vindex LaTeX-command
2879 @vindex TeX-Omega-command
2880 @vindex LaTeX-Omega-command
2881 @vindex ConTeXt-engine
2882 @vindex ConTeXt-Omega-engine
2883 @vindex TeX-engine-alist
2884 @vindex TeX-engine-alist-builtin
2885 Should you need to change the executable names related to the different
2886 engine settings, there are some variables you can tweak. Those are
2887 @code{TeX-command}, @code{LaTeX-command}, @code{TeX-Omega-command},
2888 @code{LaTeX-Omega-command}, @code{ConTeXt-engine} and
2889 @code{ConTeXt-Omega-engine}. The rest of the executables is defined
2890 directly in @code{TeX-engine-alist-builtin}. If you want to override an
2891 entry from that, add an entry to @code{TeX-engine-alist} that starts
2892 with the same symbol as that the entry in the built-in list and specify
2893 the executables you want to use instead. You can also add entries to
2894 @code{TeX-engine-alist} in order to add support for engines not covered
2897 @defopt TeX-engine-alist
2898 Alist of TeX engines and associated commands. Each entry is a list with
2899 a maximum of five elements. The first element is a symbol used to
2900 identify the engine. The second is a string describing the engine. The
2901 third is the command to be used for plain TeX. The fourth is the
2902 command to be used for LaTeX. The fifth is the command to be used for
2903 the @samp{--engine} parameter of ConTeXt's @samp{texexec} program. Each
2904 command can either be a variable or a string. An empty string or nil
2905 means there is no command available.
2908 As shown above, @AUCTeX{} handles in a special way most of the main
2909 options that can be given to the @TeX{} processors. When you need to
2910 pass to the @TeX{} processor arbitrary options not handled by @AUCTeX{},
2911 you can use the file local variable @code{TeX-command-extra-options}.
2912 @defopt TeX-command-extra-options
2913 String with the extra options to be given to the TeX processor. For
2914 example, if you need to enable the shell escape feature to compile a
2915 document, add the following line to the list of local variables of the
2918 %%% TeX-command-extra-options: "-shell-escape"
2920 By default this option is not safe as a file-local variable because a
2921 specially crafted document compiled with shell escape enabled can be
2922 used for malicious purposes.
2925 You can customize @AUCTeX{} to show the processor output as it is
2928 @defopt TeX-show-compilation
2929 If non-nil, the output of @TeX{} compilation is shown in another window.
2933 @section Viewing the Formatted Output
2936 @cindex Starting a previewer
2938 @AUCTeX{} allows you to start external programs for previewing the
2939 formatted output of your document.
2942 * Starting Viewers:: Starting viewers
2943 * I/O Correlation:: Forward and inverse search
2946 @node Starting Viewers
2947 @subsection Starting Viewers
2949 Viewers are normally invoked by pressing @kbd{C-c C-c} once the document
2950 is formatted, which will propose the View command, or by activating the
2951 respective entry in the Command menu. Alternatively you can type
2952 @kbd{C-c C-v} which calls the function @code{TeX-view}.
2954 @deffn Command TeX-view
2956 (@kbd{C-c C-v}) Start a viewer without confirmation. The viewer is
2957 started either on a region or the master file, depending on the last
2958 command issued. This is especially useful for jumping to the location
2959 corresponding to point in the viewer when using
2960 @code{TeX-source-correlate-mode}.
2963 @AUCTeX{} will try to guess which type of viewer (@acronym{DVI},
2964 PostScript or @acronym{PDF}) has to be used and what options are to be
2965 passed over to it. This decision is based on the output files present
2966 in the working directory as well as the class and style options used in
2967 the document. For example, if there is a @acronym{DVI} file in your
2968 working directory, a @acronym{DVI} viewer will be invoked. In case of a
2969 @acronym{PDF} file it will be a @acronym{PDF} viewer. If you specified
2970 a special paper format like @samp{a5paper} or use the @samp{landscape}
2971 option, this will be passed to the viewer by the appropriate options.
2972 Especially some @acronym{DVI} viewers depend on this kind of information
2973 in order to display your document correctly. In case you are using
2974 @samp{pstricks} or @samp{psfrag} in your document, a @acronym{DVI}
2975 viewer cannot display the contents correctly and a PostScript viewer
2976 will be invoked instead.
2978 The association between the tests for the conditions mentioned above and
2979 the viewers is made in the variable @code{TeX-view-program-selection}.
2980 Therefore this variable is the starting point for customization if you
2981 want to use other viewers than the ones suggested by default.
2983 @defopt TeX-view-program-selection
2984 This is a list of predicates and viewers which is evaluated from front
2985 to back in order to find out which viewer to call under the given
2986 conditions. In the first element of each list item you can reference
2987 one or more predicates defined in @code{TeX-view-predicate-list} or
2988 @code{TeX-view-predicate-list-builtin}. In the second element you can
2989 reference a viewer defined in @code{TeX-view-program-list} or
2990 @code{TeX-view-program-list-builtin}. The viewer of the first item with
2991 a positively evaluated predicate is selected.
2994 So @code{TeX-view-program-selection} only contains references to the
2995 actual implementations of predicates and viewer commands respectively
2996 which can be found elsewhere. @AUCTeX{} comes with a set of
2997 preconfigured predicates and viewer commands which are stored in the
2998 variables @code{TeX-view-predicate-list-builtin} and
2999 @code{TeX-view-program-list-builtin} respectively. If you are not
3000 satisfied with those and want to overwrite one of them or add your own
3001 definitions, you can do so via the variables
3002 @code{TeX-view-predicate-list} and @code{TeX-view-program-list}.
3004 @defopt TeX-view-predicate-list
3005 This is a list of predicates for viewer selection and invocation. The
3006 first element of each list item is a symbol and the second element a
3007 Lisp form to be evaluated. The form should return nil if the predicate
3010 A built-in predicate from @code{TeX-view-predicate-list-builtin} can be
3011 overwritten by defining a new predicate with the same symbol.
3014 @defopt TeX-view-program-list
3015 This is a list of viewer specifications each consisting of a symbolic
3016 name and either a command line or a function to be invoked when the
3017 viewer is called. If a command line is used, parts of it can be
3018 conditionalized by prefixing them with predicates from
3019 @code{TeX-view-predicate-list} or
3020 @code{TeX-view-predicate-list-builtin}. (See the doc string for the
3021 exact format to use.) The command line can also contain placeholders as
3022 defined in @code{TeX-expand-list} which are expanded before the viewer
3025 A built-in viewer spec from @code{TeX-view-program-list-builtin} can be
3026 overwritten by defining a new viewer spec with the same name.
3029 Note that the viewer selection and invocation as described above will
3030 only work if certain default settings in @AUCTeX{} are intact. For one,
3031 the whole viewer selection machinery will only be triggered if the
3032 @samp{%V} expander in @code{TeX-expand-list} is unchanged. So if you
3033 have trouble with the viewer invocation you might check if there is an
3034 older customization of the variable in place. In addition, the use of a
3035 function in @code{TeX-view-program-list} only works if the View command
3036 in @code{TeX-command-list} makes use of the hook
3037 @code{TeX-run-discard-or-function}.
3039 Note also that the implementation described above replaces an older one
3040 which was less flexible. This old implementation works with the
3041 variables @code{TeX-output-view-style} and @code{TeX-view-style} which
3042 are used to associate file types and style options with viewers. If
3043 desired you can reactivate it by using the placeholder @samp{%vv} for
3044 the View command in @code{TeX-command-list}. Note however, that it is
3045 bound to be removed from @AUCTeX{} once the new implementation proved to
3046 be satisfactory. For the time being, find a short description of the
3047 mentioned customization options below.
3049 @defopt TeX-output-view-style
3050 List of output file extensions, style options and view options. Each
3051 item of the list consists of three elements. If the first element (a
3052 regular expression) matches the output file extension, and the second
3053 element (a regular expression) matches the name of one of the style
3054 options, any occurrence of the string @code{%V} in a command in
3055 @code{TeX-command-list} will be replaced with the third element.
3058 @defopt TeX-view-style
3059 List of style options and view options. This is the predecessor of
3060 @code{TeX-output-view-style} which does not provide the possibility to
3061 specify output file extensions. It is used as a fallback in case none
3062 of the alternatives specified in @code{TeX-output-view-style} match. In
3063 case none of the entries in @code{TeX-view-style} match either, no
3064 suggestion for a viewer is made.
3067 @node I/O Correlation
3068 @subsection Forward and Inverse Search
3069 @cindex Inverse search
3070 @cindex Forward search
3071 @cindex I/O correlation
3072 @cindex Source specials
3076 Forward and inverse search refer to the correlation between the document
3077 source in the editor and the typeset document in the viewer. Forward
3078 search allows you to jump to the place in the previewed document
3079 corresponding to a certain line in the document source and inverse
3082 @findex TeX-source-correlate-mode
3083 @AUCTeX{} supports three methods for forward and inverse search: source
3084 specials (only DVI output), the pdfsync @LaTeX{} package (only PDF
3085 output) and Sync@TeX{} (any type of output). If you want to make use of
3086 forward and inverse searching with source specials or Sync@TeX{}, switch
3087 on @code{TeX-source-correlate-mode}. @xref{Processor Options}, on how
3088 to do that. The use of the pdfsync package is detected automatically if
3089 document parsing is enabled. Customize the variable
3090 @code{TeX-source-correlate-method} to select the method to use.
3092 @defopt TeX-source-correlate-method
3093 Method to use for enabling forward and inverse search. This can be
3094 @samp{source-specials} if source specials should be used, @samp{synctex}
3095 if SyncTeX should be used, or @samp{auto} if @AUCTeX{} should decide.
3097 When the variable is set to @samp{auto}, @AUCTeX{} will always use
3098 SyncTeX if your @code{latex} processor supports it, source specials
3099 otherwise. You must make sure your viewer supports the same method.
3101 It is also possible to specify a different method depending on the
3102 output, either DVI or PDF, by setting the variable to an alist of the
3105 ((dvi . <source-specials or synctex>)
3106 (pdf . <source-specials or synctex>))
3108 in which the CDR of each entry is a symbol specifying the method to be
3109 used in the corresponding mode. The default value of the variable is
3111 ((dvi . source-specials)
3114 which is compatible with the majority of viewers.
3118 Forward search happens automatically upon calling the viewer, e.g. by
3119 typing @kbd{C-c C-v} (@code{TeX-view}). This will open the viewer or
3120 bring it to front and display the output page corresponding to the
3121 position of point in the source file. @AUCTeX{} will automatically pass
3122 the necessary command line options to the viewer for this to happen.
3124 @vindex TeX-source-correlate-start-server
3125 Upon opening the viewer you will be asked if you want to start a server
3126 process (Gnuserv or Emacs server) which is necessary for inverse search.
3127 This happens only if there is no server running already. You can
3128 customize the variable @code{TeX-source-correlate-start-server} to
3129 inhibit the question and always or never start the server respectively.
3131 @defopt TeX-source-correlate-start-server
3132 If @code{TeX-source-correlate-mode} is active and a viewer is invoked,
3133 the default behavior is to ask if a server process should be started.
3134 Set this variable to @code{t} if the question should be inhibited and
3135 the server should always be started. Set it to @code{nil} if the server
3136 should never be started. Inverse search will not be available in the
3140 Inverse search, i.e. jumping to the part of your document source in
3141 Emacs corresponding to a certain position in the viewer, is triggered
3142 from the viewer, typically by a mouse click. Refer to the documentation
3143 of your viewer to find out how it has to be configured and what you have
3144 to do exactly. In xdvi you normally have to use @kbd{C-down-mouse-1}.
3147 @section Catching the errors
3150 @cindex Parsing errors
3151 @cindex Parsing TeX output
3153 @cindex Parsing @LaTeX{} errors
3154 @cindex Overfull boxes
3156 @cindex Underfull boxes
3158 Once you've formatted your document you may `debug' it, i.e. browse
3159 through the errors (La)@TeX{} reported.
3161 @deffn Command TeX-next-error @var{arg} @var{reparse}
3163 (@kbd{C-c `}) Go to the next error reported by @TeX{}. The view will
3164 be split in two, with the cursor placed as close as possible to the
3165 error in the top view. In the bottom view, the error message will be
3166 displayed along with some explanatory text.
3168 An optional numeric @var{arg}, positive or negative, specifies how many
3169 error messages to move. A negative @var{arg} means to move back to
3170 previous error messages, see also @code{TeX-previous-error}.
3172 The optional @var{reparse} argument makes @AUCTeX{} reparse the error
3173 message buffer and start the debugging from the first error. This can
3174 also be achieved by calling the function with a prefix argument
3178 @deffn Command TeX-previous-error @var{arg}
3180 (@kbd{M-g p}) Go to the previous error reported by @TeX{}. An optional
3181 numeric @var{arg} specifies how many error messages to move backward.
3182 This is like calling @code{TeX-next-error} with a negative argument.
3185 The command @code{TeX-previous-error} works only if @AUCTeX{} can parse
3186 the whole @TeX{} log buffer. This is controlled by the
3187 @code{TeX-parse-all-errors} variable.
3189 @defopt TeX-parse-all-errors
3190 If t, @AUCTeX{} automatically parses the whole output log buffer right
3191 after running a @TeX{} command, in order to collect all warnings and
3192 errors. This makes it possible to navigate back and forth between the
3193 error messages using @code{TeX-next-error} and
3194 @code{TeX-previous-error}. This is the default. If nil, @AUCTeX{} does
3195 not parse the whole output log buffer and @code{TeX-previous-error}
3199 Normally @AUCTeX{} will only report real errors, but you may as well
3200 ask it to report `bad boxes' and warnings as well.
3202 @deffn Command TeX-toggle-debug-bad-boxes
3204 (@kbd{C-c C-t C-b}) Toggle whether @AUCTeX{} should stop at bad boxes
3205 (i.e. overfull and underfull boxes) as well as normal errors.
3208 @deffn Command TeX-toggle-debug-warnings
3210 (@kbd{C-c C-t C-w}) Toggle whether @AUCTeX{} should stop at warnings as
3211 well as normal errors.
3214 As default, @AUCTeX{} will display a special help buffer containing the
3215 error reported by @TeX{} along with the documentation. There is however
3216 an `expert' option, which allows you to display the real @TeX{} output.
3218 @defopt TeX-display-help
3219 If t @AUCTeX{} will automatically display a help text whenever an error
3220 is encountered using @code{TeX-next-error} (@kbd{C-c `}). If nil a
3221 terse information about the error is displayed in the echo area. If
3222 @code{expert} @AUCTeX{} will display the output buffer with the raw
3226 When the option @code{TeX-parse-all-errors} is non-nil, you will be also
3227 able to open an overview of all errors and warnings reported by the TeX
3228 compiler. This feature requires @code{tabulated-list-mode}, shipped
3229 with GNU Emacs 24 or later.
3231 @deffn Command TeX-error-overview
3232 Show an overview of the errors and warnings occurred in the last TeX
3235 In this window you can visit the error on which point is on by pressing
3236 @key{RET}, and visit the next or previous issue by pressing @key{n} or
3237 @key{p} respectively. A prefix argument to these keys specifies how
3238 many errors to move forward or backward. You can visit an error also by
3239 clicking on its message. Press @key{q} to quit the overview.
3242 @defopt TeX-error-overview-open-after-TeX-run
3243 When this boolean variable is non-nil, the error overview will be
3244 automatically opened after running TeX if there are errors or warnings
3248 The error overview is opened in a new window of the current frame by
3249 default, but you can change this behavior by customizing the option
3250 @code{TeX-error-overview-setup}.
3252 @defopt TeX-error-overview-setup
3253 Controls the frame setup of the error overview. The possible value is:
3254 @code{separate-frame}; with a nil value the current frame is used
3257 The parameters of the separate frame can be set with the
3258 @code{TeX-error-overview-frame-parameters} option.
3260 If the display does not support multi frame, the current frame
3261 will be used regardless of the value of this variable.
3262 @vindex TeX-error-overview-frame-parameters
3266 @section Checking for problems
3268 @cindex @code{lacheck}
3269 @cindex @code{chktex}
3270 @cindex Finding errors
3271 @cindex Running @code{lacheck}
3272 @cindex Running @code{chktex}
3276 Running @TeX{} or @LaTeX{} will only find regular errors in the
3277 document, not examples of bad style. Furthermore, description of the
3278 errors may often be confusing. The utilities @code{lacheck} and
3279 @code{chktex} can be used to find style errors, such as forgetting to
3280 escape the space after an abbreviation or using @samp{...} instead of
3281 @samp{\ldots} and other similar problems. You start @code{lacheck} with
3282 @kbd{C-c C-c Check @key{RET}} and @code{chktex} with @kbd{C-c C-c ChkTeX
3283 @key{RET}}. The result will be a list of errors in the
3284 @samp{*compilation*} buffer. You can go through the errors with
3285 @kbd{C-x `} (@code{next-error}, @pxref{Compilation,,,emacs,The Emacs
3286 Editor}), which will move point to the location of the next error.
3288 Each of the two utilities will find some errors the other doesn't, but
3289 @code{chktex} is more configurable, allowing you to create your own
3290 errors. You may need to install the programs before using them. You
3291 can get @code{lacheck} from
3292 @file{<URL:ftp://ftp.ctan.org/tex-archive/support/lacheck/>} and
3294 @file{<URL:ftp://ftp.ctan.org/tex-archive/support/chktex/>}.
3297 @section Controlling the output
3298 @cindex Controlling the output
3300 @cindex Redisplay output
3302 @cindex Killing a process
3303 @cindex Finding the master file
3305 @cindex Stopping a process
3306 @cindex Current file
3307 @cindex Finding the current file
3309 A number of commands are available for controlling the output of an
3310 application running under @AUCTeX{}
3312 @deffn Command TeX-kill-job
3314 (@kbd{C-c C-k}) Kill currently running external application.
3315 This may be either of @TeX{}, @LaTeX{}, previewer, Bib@TeX{}, etc.
3318 @deffn Command TeX-recenter-output-buffer
3320 (@kbd{C-c C-l}) Recenter the output buffer so that the bottom line is
3324 @deffn Command TeX-home-buffer
3326 (@kbd{C-c ^}) Go to the `master' file in the document associated with
3327 the current buffer, or if already there, to the file where the current
3328 process was started.
3332 @section Cleaning intermediate and output files
3335 @deffn Command TeX-clean
3336 @vindex plain-TeX-clean-intermediate-suffixes
3337 @vindex plain-TeX-clean-output-suffixes
3338 @vindex LaTeX-clean-intermediate-suffixes
3339 @vindex LaTeX-clean-output-suffixes
3340 @vindex docTeX-clean-intermediate-suffixes
3341 @vindex docTeX-clean-output-suffixes
3342 @vindex Texinfo-clean-intermediate-suffixes
3343 @vindex Texinfo-clean-output-suffixes
3344 @vindex ConTeXt-clean-intermediate-suffixes
3345 @vindex ConTeXt-clean-output-suffixes
3346 Remove generated intermediate files. In case a prefix argument is
3347 given, remove output files as well.
3349 Canonical access to the function is provided by the @samp{Clean} and
3350 @samp{Clean All} entries in @code{TeX-command-list}, invokable with
3351 @kbd{C-c C-c} or the Command menu.
3353 The patterns governing which files to remove can be adapted separately
3354 for each @AUCTeX{} mode by means of the variables
3355 @code{plain-TeX-clean-intermediate-suffixes},
3356 @code{plain-TeX-clean-output-suffixes},
3357 @code{LaTeX-clean-intermediate-suffixes},
3358 @code{LaTeX-clean-output-suffixes},
3359 @code{docTeX-clean-intermediate-suffixes},
3360 @code{docTeX-clean-output-suffixes},
3361 @code{Texinfo-clean-intermediate-suffixes},
3362 @code{Texinfo-clean-output-suffixes},
3363 @code{ConTeXt-clean-intermediate-suffixes} and
3364 @code{ConTeXt-clean-output-suffixes}.
3367 @defopt TeX-clean-confirm
3368 Control if deletion of intermediate and output files has to be confirmed
3369 before it is actually done. If non-nil, ask before deleting files.
3373 @section Documentation about macros and packages
3374 @cindex Documentation
3376 @deffn Command TeX-doc
3378 (@kbd{C-c ?}) Get documentation about macros, packages or @TeX{} &
3379 Co. in general. The function will prompt for the name of a command or
3380 manual, providing a list of available keywords for completion. If point
3381 is on a command or word with available documentation, this will be
3382 suggested as default.
3384 In case no documentation could be found, a prompt for querying the
3385 @samp{texdoc} program is shown, should the latter be available.
3387 The command can be invoked by the key binding mentioned above as well as
3388 the @samp{Find Documentation...} entry in the mode menu.
3392 @chapter Customization and Extension
3395 * Modes and Hooks:: Modes and Hooks
3396 * Multifile:: Multifile Documents
3397 * Parsing Files:: Automatic Parsing of @TeX{} Files
3398 * Internationalization:: Language Support
3399 * Automatic:: Automatic Customization
3400 * Style Files:: Writing Your Own Style Support
3403 @node Modes and Hooks
3404 @section Modes and Hooks
3406 @AUCTeX{} supports a wide variety of derivatives and extensions of
3407 @TeX{}. Besides plain @TeX{} those are @LaTeX{}, AMS-@TeX{},
3408 @ConTeXt{}, Texinfo and doc@TeX{}. For each of them there is a separate
3409 major mode in @AUCTeX{} and each major mode runs @code{text-mode-hook},
3410 @code{TeX-mode-hook} as well as a hook special to the mode in this
3411 order. The following table provides an overview of the respective mode
3412 functions and hooks.
3414 @multitable {Plain @TeX{}} {@code{plain-TeX-mode}} {@code{plain-TeX-mode-hook}}
3415 @headitem Type @tab Mode function @tab Hook
3416 @item Plain @TeX{} @tab @code{plain-TeX-mode} @tab @code{plain-TeX-mode-hook}
3417 @item @LaTeX{} @tab @code{LaTeX-mode} @tab @code{LaTeX-mode-hook}
3418 @item AMS-@TeX{} @tab @code{ams-tex-mode} @tab @code{AmS-TeX-mode-hook}
3419 @item @ConTeXt{} @tab @code{ConTeXt-mode} @tab @code{ConTeXt-mode-hook}
3420 @item Texinfo @tab @code{Texinfo-mode} @tab @code{Texinfo-mode-hook}
3421 @item Doc@TeX{} @tab @code{docTeX-mode} @tab @code{docTeX-mode-hook}
3423 @findex plain-TeX-mode
3424 @vindex plain-TeX-mode-hook
3426 @vindex LaTeX-mode-hook
3427 @findex AmS-TeX-mode
3428 @vindex AmS-TeX-mode-hook
3429 @findex ConTeXt-mode
3430 @vindex ConTeXt-mode-hook
3431 @findex Texinfo-mode
3432 @vindex Texinfo-mode-hook
3434 @vindex docTeX-mode-hook
3436 If you need to make a customization via a hook which is only relevant
3437 for one of the modes listed above, put it into the respective mode hook,
3438 if it is relevant for any @AUCTeX{} mode, add it to @code{TeX-mode-hook}
3439 and if it is relevant for all text modes, append it to
3440 @code{text-mode-hook}.
3443 @section Multifile Documents
3444 @cindex Multifile Documents
3446 @cindex Documents with multiple files
3447 @cindex Multiple Files
3455 You may wish to spread a document over many files (as you are likely to do if
3456 there are multiple authors, or if you have not yet discovered the power
3457 of the outline commands (@pxref{Outline})). This can be done by having a
3458 ``master'' file in which you include the various files with the @TeX{}
3459 macro @samp{\input} or the @LaTeX{} macro @samp{\include}. These
3460 files may also include other files themselves. However, to format the
3461 document you must run the commands on the top level master file.
3463 When you, for example, ask @AUCTeX{} to run a command on the master file,
3464 it has no way of knowing the name of the master file. By default,
3465 it will assume that the current file is the master file. If you insert
3466 the following in your @file{.emacs} file @AUCTeX{} will use a more
3470 (setq-default TeX-master nil) ; Query for master file.
3473 If @AUCTeX{} finds the line indicating the end of the header in a master
3474 file (@code{TeX-header-end}), it can figure out for itself that this is
3475 a master file. Otherwise, it will ask for the name of the master file
3476 associated with the buffer. To avoid asking you again, @AUCTeX{} will
3477 automatically insert the name of the master file as a file variable
3478 (@pxref{File Variables,,,emacs,The Emacs Editor}). You can also insert
3479 the file variable yourself, by putting the following text at the end of
3481 @findex TeX-header-end
3484 %%% Local Variables:
3485 %%% TeX-master: "master"
3489 You should always set this variable to the name of the top level document. If
3490 you always use the same name for your top level documents, you can set
3491 @code{TeX-master} in your @file{.emacs} file.
3494 (setq-default TeX-master "master") ; All master files called "master".
3498 The master file associated with the current buffer. If the file being
3499 edited is actually included from another file, then you can tell @AUCTeX{}
3500 the name of the master file by setting this variable. If there are
3501 multiple levels of nesting, specify the top level file.
3503 If this variable is @code{nil}, @AUCTeX{} will query you for the
3506 If the variable is @code{t}, then @AUCTeX{} will assume the file is a master
3509 If the variable is @code{shared}, then @AUCTeX{} will query for the name,
3510 but will not change the file.
3513 @defopt TeX-one-master
3514 Regular expression matching ordinary @TeX{} files.
3516 You should set this variable to match the name of all files, for which
3517 it is a good idea to append a @code{TeX-master} file variable entry
3518 automatically. When @AUCTeX{} adds the name of the master file as a
3519 file variable, it does not need to ask next time you edit the file.
3521 If you dislike @AUCTeX{} automatically modifying your files, you can
3522 set this variable to @samp{"<none>"}. By default, @AUCTeX{} will modify
3523 any file with an extension of @samp{.tex}.
3526 @deffn Command TeX-master-file-ask
3528 (@kbd{C-c _}) Query for the name of a master file and add the respective
3529 File Variables (@pxref{File Variables,,,emacs,The Emacs Editor}) to the
3530 file for setting this variable permanently.
3532 @AUCTeX{} will not ask for a master file when it encounters existing
3533 files. This function shall give you the possibility to insert the
3537 @AUCTeX{} keeps track of macros, environments, labels, and style
3538 files that are used in a given document. For this to work with
3539 multifile documents, @AUCTeX{} has to have a place to put the
3540 information about the files in the document. This is done by having an
3541 @file{auto} subdirectory placed in the directory where your document is
3542 located. Each time you save a file, @AUCTeX{} will write information
3543 about the file into the @file{auto} directory. When you load a file,
3544 @AUCTeX{} will read the information in the @file{auto} directory
3545 about the file you loaded @emph{and the master file specified by
3546 @code{TeX-master}}. Since the master file (perhaps indirectly) includes
3547 all other files in the document, @AUCTeX{} will get information from
3548 all files in the document. This means that you will get from each file,
3549 for example, completion for all labels defined anywhere in the document.
3551 @AUCTeX{} will create the @file{auto} directory automatically if
3552 @code{TeX-auto-save} is non-nil. Without it, the files in the document
3553 will not know anything about each other, except for the name of the
3554 master file. @xref{Automatic Local}.
3556 @deffn Command TeX-save-document
3558 (@kbd{C-c C-d}) Save all buffers known to belong to the current document.
3561 @defopt TeX-save-query
3562 If non-nil, then query the user before saving each file with
3563 @code{TeX-save-document}.
3568 @section Automatic Parsing of @TeX{} Files
3569 @cindex Parsing @TeX{}
3570 @cindex Automatic Parsing
3575 @AUCTeX{} depends heavily on being able to extract information from the
3576 buffers by parsing them. Since parsing the buffer can be somewhat slow,
3577 the parsing is initially disabled. You are encouraged to enable them by
3578 adding the following lines to your @file{.emacs} file.
3581 (setq TeX-parse-self t) ; Enable parse on load.
3582 (setq TeX-auto-save t) ; Enable parse on save.
3585 The latter command will make @AUCTeX{} store the parsed information in
3586 an @file{auto} subdirectory in the directory each time the @TeX{} files
3587 are stored, @pxref{Automatic Local}. If @AUCTeX{} finds the pre-parsed
3588 information when loading a file, it will not need to reparse the buffer.
3589 The information in the @file{auto} directory is also useful for
3590 multifile documents, @pxref{Multifile}, since it allows each file to
3591 access the parsed information from all the other files in the document.
3592 This is done by first reading the information from the master file, and
3593 then recursively the information from each file stored in the master
3596 The variables can also be done on a per file basis, by changing the file
3600 %%% Local Variables:
3601 %%% TeX-parse-self: t
3602 %%% TeX-auto-save: t
3606 Even when you have disabled the automatic parsing, you can force the
3607 generation of style information by pressing @kbd{C-c C-n}. This is
3608 often the best choice, as you will be able to decide when it is
3609 necessary to reparse the file.
3611 @defopt TeX-parse-self
3612 Parse file after loading it if no style hook is found for it.
3615 @defopt TeX-auto-save
3616 Automatically save style information when saving the buffer.
3619 @deffn Command TeX-normal-mode @var{arg}
3621 (@kbd{C-c C-n}) Remove all information about this buffer, and apply the
3622 style hooks again. Save buffer first including style information. With
3623 optional argument, also reload the style hooks.
3626 When @AUCTeX{} saves your buffer, it can optionally convert all tabs in
3627 your buffer into spaces.
3628 Tabs confuse @AUCTeX{}'s error message parsing and so should generally be
3629 avoided. However, tabs are significant in some environments, and so by
3630 default @AUCTeX{} does not remove them.
3631 To convert tabs to spaces when saving a buffer, insert the
3632 following in your @file{.emacs} file:
3635 (setq TeX-auto-untabify t)
3638 @defopt TeX-auto-untabify
3639 Automatically remove all tabs from a file before saving it.
3642 Instead of disabling the parsing entirely, you can also speed it
3643 significantly up by limiting the information it will search for (and
3644 store) when parsing the buffer. You can do this by setting the default
3645 values for the buffer local variables @code{TeX-auto-regexp-list} and
3646 @code{TeX-auto-parse-length} in your @file{.emacs} file.
3649 ;; Only parse LaTeX class and package information.
3650 (setq-default TeX-auto-regexp-list 'LaTeX-auto-minimal-regexp-list)
3651 ;; The class and package information is usually near the beginning.
3652 (setq-default TeX-auto-parse-length 2000)
3655 This example will speed the parsing up significantly, but @AUCTeX{}
3656 will no longer be able to provide completion for labels, macros,
3657 environments, or bibitems specified in the document, nor will it know
3658 what files belong to the document.
3660 These variables can also be specified on a per file basis, by changing
3661 the file local variables.
3664 %%% Local Variables:
3665 %%% TeX-auto-regexp-list: TeX-auto-full-regexp-list
3666 %%% TeX-auto-parse-length: 999999
3670 @defopt TeX-auto-regexp-list
3671 List of regular expressions used for parsing the current file.
3674 @defopt TeX-auto-parse-length
3675 Maximal length of @TeX{} file that will be parsed.
3678 The pre-specified lists of regexps are defined below. You can use these
3679 before loading @AUCTeX{} by quoting them, as in the example above.
3681 @defvr Constant TeX-auto-empty-regexp-list
3685 @defvr Constant LaTeX-auto-minimal-regexp-list
3686 Only parse @LaTeX{} class and packages.
3689 @defvr Constant LaTeX-auto-label-regexp-list
3690 Only parse @LaTeX{} labels.
3693 @defvr Constant LaTeX-auto-index-regexp-list
3694 Only parse @LaTeX{} index and glossary entries.
3697 @defvr Constant LaTeX-auto-class-regexp-list
3698 Only parse macros in @LaTeX{} classes and packages.
3701 @defvr Constant LaTeX-auto-pagestyle-regexp-list
3702 Only parse @LaTeX{} pagestyles.
3705 @defvr Constant LaTeX-auto-counter-regexp-list
3706 Only parse @LaTeX{} counters.
3709 @defvr Constant LaTeX-auto-length-regexp-list
3710 Only parse @LaTeX{} lengths.
3713 @defvr Constant LaTeX-auto-savebox-regexp-list
3714 Only parse @LaTeX{} saveboxes.
3717 @defvr Constant LaTeX-auto-regexp-list
3718 Parse common @LaTeX{} commands.
3721 @defvr Constant plain-TeX-auto-regexp-list
3722 Parse common plain @TeX{} commands.
3725 @defvr Constant TeX-auto-full-regexp-list
3726 Parse all @TeX{} and @LaTeX{} commands that @AUCTeX{} can use.
3729 @node Internationalization
3730 @section Language Support
3731 @cindex Internationalization
3732 @cindex Language Support
3733 @cindex Character set
3734 @cindex National letters
3735 @cindex CJK language
3740 @cindex ASCII p@TeX{}
3745 @cindex CJK-@LaTeX{}
3749 @TeX{} and Emacs are usable for European (Latin, Cyrillic, Greek) based
3750 languages. Some @LaTeX{} and EmacsLisp packages are available for easy
3751 typesetting and editing documents in European languages.
3753 @c Some Texinfo macros are not used because they require quite recent
3754 @c texinfo versions (2005-03-05):
3755 @c Second arg of @acronym is available with 4.7, @comma is available in
3756 @c 4.7, @abbr is available in 4.8.
3757 @c -> @abbr{MULE, MULtilingual Enhancement to GNU Emacs}
3758 @c -> @acronym{CJK, Chinese@comma{} Japanese@comma{} and Korean}
3760 For @acronym{CJK} (Chinese, Japanese, and Korean) languages, Emacs or
3761 XEmacs with @acronym{MULE} (MULtilingual Enhancement to GNU Emacs)
3762 support is required. @acronym{MULE} is part of Emacs by default since
3763 Emacs 20. XEmacs has to be configured with the @samp{--with-mule}
3764 option. Special versions of @TeX{} are needed for @acronym{CJK}
3765 languages: C@TeX{} and China@TeX{} for Chinese, ASCII p@TeX{} and NTT
3766 j@TeX{} for Japanese, H@LaTeX{} and k@TeX{} for Korean. The
3767 @acronym{CJK}-@LaTeX{} package is required for supporting multiple
3768 @acronym{CJK} scripts within a single document.
3770 Note that Unicode is not fully supported in Emacs 21 and XEmacs 21.
3771 @acronym{CJK} characters are not usable. Please use the
3772 @acronym{MULE}-@acronym{UCS} EmacsLisp package or Emacs 22 (not released
3773 yet) if you need @acronym{CJK}.
3775 @c FIXME: We need more information for CTeX, ChinaTeX, KTeX, and HLaTeX.
3778 * European:: Using @AUCTeX{} with European Languages
3779 * Japanese:: Using @AUCTeX{} with Japanese
3783 @subsection Using @AUCTeX{} with European Languages
3785 @cindex European Characters
3786 @cindex ISO 8859 Latin 1
3788 @cindex ISO 8859 Latin 2
3792 @subsubsection Typing and Displaying Non-ASCII Characters
3794 First you will need a way to write non-ASCII characters. You can either
3795 use macros, or teach @TeX{} about the ISO character sets. I prefer the
3796 latter, it has the advantage that the usual standard emacs word
3797 movement and case change commands will work.
3799 With @LaTeX{}2e, just add @samp{\usepackage[latin1]@{inputenc@}}. Other
3800 languages than Western European ones will probably have other encoding
3803 To be able to display non-ASCII characters you will need an appropriate
3804 font and a version of GNU Emacs capable of displaying 8-bit characters
3805 (e.g. Emacs 21). The manner in which this is supported differs between
3806 Emacsen, so you need to take a look at your respective documentation.
3808 A compromise is to use an European character set when editing the file,
3809 and convert to @TeX{} macros when reading and writing the files.
3813 @cindex @file{iso-cvt.el}
3814 Much like @file{iso-tex.el} but is bundled with Emacs 19.23 and later.
3817 @cindex @file{x-compose.el}
3818 Similar package bundled with new versions of XEmacs.
3822 a much more complete package for both Emacs and XEmacs that can also
3823 handle a lot of mathematical characters and input methods.
3826 @subsubsection Style Files for Different Languages
3829 @AUCTeX{} supports style files for several languages. Each style file
3830 may modify @AUCTeX{} to better support the language, and will run
3831 a language specific hook that will allow you to for example change
3832 ispell dictionary, or run code to change the keyboard remapping. The
3833 following will for example choose a Danish dictionary for documents
3834 including @samp{\usepackage[danish]@{babel@}}.
3835 This requires parsing to be enabled, @pxref{Parsing Files}.
3838 (add-hook 'TeX-language-dk-hook
3839 (lambda () (ispell-change-dictionary "danish")))
3842 The following style files are recognized:
3844 @c In alphabetic order of the hooks:
3845 @vindex TeX-language-bg-hook
3846 @vindex TeX-language-cz-hook
3847 @vindex TeX-language-dk-hook
3848 @vindex TeX-language-en-hook
3849 @vindex TeX-language-nl-hook
3850 @vindex TeX-language-de-hook
3851 @vindex TeX-language-it-hook
3852 @vindex TeX-language-is-hook
3853 @vindex TeX-language-pl-hook
3854 @vindex TeX-language-sk-hook
3855 @vindex TeX-language-sv-hook
3868 Runs style hook @code{TeX-language-bg-hook}. Gives @samp{"} word
3869 syntax, makes the @key{"} key insert a literal @samp{"}. Typing @key{"}
3870 twice will insert insert @samp{"`} or @samp{"'} depending on context.
3871 Typing @key{-} twice will insert @samp{"=}, three times @samp{--}.
3874 Runs style hook @code{TeX-language-cz-hook}. Pressing @key{"} will
3875 insert @samp{\uv@{} and @samp{@}} depending on context.
3877 @c Is the difference between dk and danish really intented?
3879 Runs style hook @code{TeX-language-dk-hook}. Pressing @key{"} will
3880 insert @samp{"`} and @samp{"'} depending on context. Typing @key{-}
3881 twice will insert @samp{"=}, i.e. a hyphen string allowing hyphenation
3882 in the composing words.
3883 @c dk.sty seems to be obsolete, so we don't want to encourage using it.
3885 @c Runs style hook @code{TeX-language-dk-hook}.
3888 Runs style hook @code{TeX-language-nl-hook}.
3891 Runs style hook @code{TeX-language-en-hook}.
3895 Runs style hook @code{TeX-language-fr-hook}. Pressing @key{"} will
3896 insert @samp{\\og} and @samp{\\fg} depending on context. Note that the
3897 language name for customizing @code{TeX-quote-language-alist} is
3902 Runs style hook @code{TeX-language-de-hook}. Gives @samp{"} word
3903 syntax, makes the @key{"} key insert a literal @samp{"}. Pressing the
3904 key twice will give you opening or closing German quotes (@samp{"`} or
3905 @samp{"'}). Typing @key{-} twice will insert @samp{"=}, three times
3909 Runs style hook @code{TeX-language-is-hook}. Gives @samp{"} word
3910 syntax, makes the @key{"} key insert a literal @samp{"}. Typing @key{"}
3911 twice will insert insert @samp{"`} or @samp{"'} depending on context.
3912 Typing @key{-} twice will insert @samp{"=}, three times @samp{--}.
3915 Runs style hook @code{TeX-language-it-hook}. Pressing @key{"} will
3916 insert @samp{"<} and @samp{">} depending on context.
3919 Runs style hook @code{TeX-language-pl-hook}. Gives @samp{"} word syntax
3920 and makes the @key{"} key insert a literal @samp{"}. Pressing @key{"}
3921 twice will insert @samp{"`} or @samp{"'} depending on context.
3924 Runs style hook @code{TeX-language-pl-hook}. Makes the @key{"} key
3925 insert a literal @samp{"}. Pressing @key{"} twice will insert @samp{,,}
3926 or @samp{''} depending on context.
3929 Runs style hook @code{TeX-language-sk-hook}. Pressing @key{"} will
3930 insert @samp{\uv@{} and @samp{@}} depending on context.
3933 Runs style hook @code{TeX-language-sv-hook}. Pressing @key{"} will
3934 insert @samp{''}. Typing @key{-} twice will insert @samp{"=}, three
3938 Replacement of language-specific hyphen strings like @samp{"=} with
3939 dashes does not require to type @key{-} three times in a row. You can
3940 put point after the hypen string anytime and trigger the replacement by
3943 In case you are not satisfied with the suggested behavior of quote and
3944 hyphen insertion you can change it by customizing the variables
3945 @code{TeX-quote-language-alist} and
3946 @code{LaTeX-babel-hyphen-language-alist} respectively.
3948 @defopt TeX-quote-language-alist
3949 Used for overriding the default language-specific quote insertion
3950 behavior. This is an alist where each element is a list consisting of
3951 four items. The first item is the name of the language in concern as a
3952 string. See the list of supported languages above. The second item is
3953 the opening quotation mark. The third item is the closing quotation
3954 mark. Opening and closing quotation marks can be specified directly as
3955 strings or as functions returning a string. The fourth item is a
3956 boolean controlling quote insertion. It should be non-nil if if the
3957 special quotes should only be used after inserting a literal @samp{"}
3958 character first, i.e. on second key press.
3961 @defopt LaTeX-babel-hyphen-language-alist
3962 Used for overriding the behavior of hyphen insertion for specific
3963 languages. Every element in this alist is a list of three items. The
3964 first item should specify the affected language as a string. The second
3965 item denotes the hyphen string to be used as a string. The third item,
3966 a boolean, controls the behavior of hyphen insertion and should be
3967 non-nil if the special hyphen should be inserted after inserting a
3968 literal @samp{-} character, i.e. on second key press.
3971 The defaults of hyphen insertion are defined by the variables
3972 @code{LaTeX-babel-hyphen} and @code{LaTeX-babel-hyphen-after-hyphen}
3975 @defopt LaTeX-babel-hyphen
3976 String to be used when typing @key{-}. This usually is a hyphen
3977 alternative or hyphenation aid provided by @samp{babel} and the related
3978 language style files, like @samp{"=}, @samp{"~} or @samp{"-}.
3980 Set it to an empty string or nil in order to disable language-specific
3984 @defopt LaTeX-babel-hyphen-after-hyphen
3985 Control insertion of hyphen strings. If non-nil insert normal hyphen on
3986 first key press and swap it with the language-specific hyphen string
3987 specified in the variable @code{LaTeX-babel-hyphen} on second key press.
3988 If nil do it the other way round.
3992 @subsection Using @AUCTeX{} with Japanese @TeX{}
4000 @cindex ASCII p@TeX{}
4003 @cindex @file{tex-jp.el}
4004 @vindex TeX-default-mode
4005 @vindex japanese-TeX-command-default
4006 @vindex japanese-LaTeX-command-default
4007 @vindex japanese-LaTeX-default-style
4009 To write Japanese text with @AUCTeX{}, you need to have versions of
4010 @TeX{} and Emacs that support Japanese. There exist at least two
4011 variants of @TeX{} for Japanese text (NTT j@TeX{} and ASCII p@TeX{}).
4012 @AUCTeX{} can be used with @acronym{MULE, MULtilingual Enhancement to GNU
4013 Emacs} supported Emacsen.
4015 To use the Japanese @TeX{} variants, simply activate
4016 @code{japanese-plain-tex-mode} or @code{japanese-latex-mode} and
4017 everything should work. If not, send mail to Masayuki Ataka
4018 @samp{<ataka@@milk.freemail.ne.jp>}, who kindly donated the code for
4019 supporting Japanese in @AUCTeX{}. None of the primary @AUCTeX{}
4020 maintainers understand Japanese, so they cannot help you.
4022 If you usually use @AUCTeX{} in Japanese, setting the following
4023 variables is useful.
4025 @defopt TeX-default-mode
4026 Mode to enter for a new file when it cannott be determined whether the
4027 file is plain @TeX{} or @LaTeX{} or what.
4029 If you want to enter Japanese @LaTeX{} mode whenever this may happen,
4030 set the variable like this:
4032 (setq TeX-default-mode 'japanese-latex-mode)
4036 @defopt japanese-TeX-command-default
4037 The default command for @code{TeX-command} in Japanese @TeX{} mode.
4039 The default value is @samp{"pTeX"}.
4042 @defopt japanese-LaTeX-command-default
4043 The default command for @code{TeX-command} in Japanese @LaTeX{} mode.
4045 The default value is @samp{"LaTeX"}.
4048 @defopt japanese-LaTeX-default-style
4049 The default style/class when creating a new Japanese @LaTeX{} document.
4051 The default value is @samp{"jarticle"}.
4054 See @file{tex-jp.el} for more information.
4057 @section Automatic Customization
4058 @cindex Automatic Customization
4059 @cindex Extracting @TeX{} symbols
4061 @cindex @file{auto} directories.
4062 @cindex Parsing @TeX{}
4063 @cindex @TeX{} parsing
4064 @cindex Generating symbols
4066 Since @AUCTeX{} is so highly customizable, it makes sense that it is able
4067 to customize itself. The automatic customization consists of scanning
4068 @TeX{} files and extracting symbols, environments, and things like that.
4070 The automatic customization is done on three different levels. The
4071 global level is the level shared by all users at your site, and consists
4072 of scanning the standard @TeX{} style files, and any extra styles added
4073 locally for all users on the site. The private level deals with those
4074 style files you have written for your own use, and use in different
4075 documents. You may have a @file{~/lib/TeX/} directory where you store
4076 useful style files for your own use. The local level is for a specific
4077 directory, and deals with writing customization for the files for your
4078 normal @TeX{} documents.
4080 If compared with the environment variable @code{TEXINPUTS}, the
4081 global level corresponds to the directories built into @TeX{}. The
4082 private level corresponds to the directories you add yourself, except for
4083 @file{.}, which is the local level.
4086 * Automatic Global:: Automatic Customization for the Site
4087 * Automatic Private:: Automatic Customization for a User
4088 * Automatic Local:: Automatic Customization for a Directory
4091 By default @AUCTeX{} will search for customization files in all the
4092 global, private, and local style directories, but you can also set the
4093 path directly. This is useful if you for example want to add another
4094 person's style hooks to your path. Please note that all matching files
4095 found in @code{TeX-style-path} are loaded, and all hooks defined in the
4096 files will be executed.
4098 @defopt TeX-style-path
4099 List of directories to search for @AUCTeX{} style files.
4100 Each must end with a slash.
4103 By default, when @AUCTeX{} searches a directory for files, it will
4104 recursively search through subdirectories.
4106 @defopt TeX-file-recurse
4107 Whether to search @TeX{} directories recursively: nil means do not
4108 recurse, a positive integer means go that far deep in the directory
4109 hierarchy, t means recurse indefinitely.
4112 By default, @AUCTeX{} will ignore files named @file{.}, @file{..},
4113 @file{SCCS}, @file{RCS}, and @file{CVS}.
4115 @defopt TeX-ignore-file
4116 Regular expression matching file names to ignore.
4118 These files or directories will not be considered when searching for
4119 @TeX{} files in a directory.
4122 @node Automatic Global
4123 @subsection Automatic Customization for the Site
4124 @cindex Global style hook directory
4125 @cindex Global macro directory
4126 @cindex Site macro directory
4127 @cindex Global @TeX{} macro directory
4128 @cindex Site @TeX{} macro directory
4129 @cindex Global directories
4130 @cindex Site information
4132 Assuming that the automatic customization at the global level was done
4133 when @AUCTeX{} was installed, your choice is now: will you use it? If
4134 you use it, you will benefit by having access to all the symbols and
4135 environments available for completion purposes. The drawback is slower
4136 load time when you edit a new file and perhaps too many confusing
4137 symbols when you try to do a completion.
4139 You can disable the automatic generated global style hooks by setting
4140 the variable @code{TeX-auto-global} to nil.
4142 @defopt TeX-macro-global
4143 Directories containing the site's @TeX{} style files.
4146 @defopt TeX-style-global
4147 Directory containing hand generated @TeX{} information.
4148 Must end with a slash.
4150 These correspond to @TeX{} macros shared by all users of a site.
4153 @defopt TeX-auto-global
4154 Directory containing automatically generated information.
4156 For storing automatic extracted information about the @TeX{} macros
4157 shared by all users of a site.
4160 @node Automatic Private
4161 @subsection Automatic Customization for a User
4162 @cindex Private style hook directory
4163 @cindex Private macro directory
4164 @cindex Personal macro directory
4165 @cindex Private @TeX{} macro directory
4166 @cindex Personal @TeX{} macro directory
4167 @cindex Private directories
4168 @cindex Personal information
4170 You should specify where you store your private @TeX{} macros, so
4171 @AUCTeX{} can extract their information. The extracted information will
4172 go to the directories listed in @code{TeX-auto-private}
4174 Use @kbd{M-x TeX-auto-generate @key{RET}} to extract the information.
4176 @defopt TeX-macro-private
4177 Directories where you store your personal @TeX{} macros. The value
4178 defaults to the directories listed in the @samp{TEXINPUTS} and
4179 @samp{BIBINPUTS} environment variables or to the respective directories
4180 in @code{$TEXMFHOME} if no results can be obtained from the environment
4184 @defopt TeX-auto-private
4185 List of directories containing automatically generated @AUCTeX{} style
4186 files. These correspond to the personal @TeX{} macros.
4189 @deffn Command TeX-auto-generate @var{TEX} @var{AUTO}
4190 (@kbd{M-x TeX-auto-generate @key{RET}}) Generate style hook for
4191 @var{TEX} and store it in @var{AUTO}. If @var{TEX} is a directory,
4192 generate style hooks for all files in the directory.
4195 @defopt TeX-style-private
4196 List of directories containing hand generated @AUCTeX{} style files.
4197 These correspond to the personal @TeX{} macros.
4200 @node Automatic Local
4201 @subsection Automatic Customization for a Directory
4202 @cindex Local style hooks
4203 @cindex Updating style hooks
4204 @cindex Automatic updating style hooks
4205 @cindex Local style hooks
4206 @cindex Local style directory
4208 @AUCTeX{} can update the style information about a file each time you
4209 save it, and it will do this if the directory @code{TeX-auto-local}
4210 exist. @code{TeX-auto-local} is by default set to @samp{"auto"}, so
4211 simply creating an @file{auto} directory will enable automatic saving of
4214 The advantage of doing this is that macros, labels, etc. defined in any
4215 file in a multifile document will be known in all the files in the
4216 document. The disadvantage is that saving will be slower. To disable,
4217 set @code{TeX-auto-local} to nil.
4219 @defopt TeX-style-local
4220 Directory containing hand generated @TeX{} information.
4221 Must end with a slash.
4223 These correspond to @TeX{} macros found in the current directory.
4226 @defopt TeX-auto-local
4227 Directory containing automatically generated @TeX{} information.
4228 Must end with a slash.
4230 These correspond to @TeX{} macros found in the current directory.
4234 @section Writing Your Own Style Support
4237 @cindex @file{style}
4239 @xref{Automatic}, for a discussion about automatically generated global,
4240 private, and local style files. The hand generated style files are
4241 equivalent, except that they by default are found in @file{style}
4242 directories instead of @file{auto} directories.
4245 * Simple Style:: A Simple Style File
4246 * Adding Macros:: Adding Support for Macros
4247 * Adding Environments:: Adding Support for Environments
4248 * Adding Other:: Adding Other Information
4249 * Hacking the Parser:: Automatic Extraction of New Things
4252 If you write some useful support for a public @TeX{} style file, please
4256 @subsection A Simple Style File
4257 @cindex @file{book.el}
4258 @cindex Sample style file
4260 @cindex Example of a style file.
4262 @cindex Adding a style hook
4264 Here is a simple example of a style file.
4267 ;;; book.el - Special code for book style.
4272 (LaTeX-largest-level-set "chapter"))
4276 The example is from the @AUCTeX{} sources and is loaded for any @LaTeX{}
4277 document using the book document class (or style before @LaTeX{}2e).
4278 The file specifies that the largest kind of section in such a document
4279 is chapter. The interesting thing to notice is that the style file
4280 defines an (anonymous) function, and adds it to the list of loaded style
4281 hooks by calling @code{TeX-add-style-hook}.
4283 The first time the user indirectly tries to access some style-specific
4284 information, such as the largest sectioning command available, the style
4285 hooks for all files directly or indirectly read by the current document
4286 are executed. The actual files will only be evaluated once, but the
4287 hooks will be called for each buffer using the style file.
4289 Note that the basename of the style file and the name of the style hook
4290 should usually be identical.
4292 @defun TeX-add-style-hook @var{style} @var{hook} &optional @var{dialect-expr}
4293 Add @var{hook} to the list of functions to run when we use the @TeX{}
4294 file @var{style} and the current dialect is one in the set derived from
4295 @var{dialect-expr}. When @var{dialect-expr} is omitted, then @var{hook}
4296 is allowed to be run whatever the current dialect is.
4298 @var{dialect-expr} may be one of:
4302 A symbol indicating a singleton containing one basic @TeX{} dialect,
4303 this symbol shall be selected among:
4306 For all files in @LaTeX{} mode, or any mode derived thereof
4308 For all files in Bib@TeX{} mode, or any mode derived thereof
4310 For all files in @acronym{Texinfo} mode.
4313 A logical expression like:
4315 @item (or @var{dialect-expression1} @dots{} @var{dialect-expression_@var{n}})
4316 For union of the sets of dialects corresponding to @var{dialect-expression1}
4317 through @var{dialect-expression_@var{n}}
4318 @item (and @var{dialect-expression1} @dots{} @var{dialect-expression_@var{n}})
4319 For intersection of the sets of dialects corresponding to
4320 @var{dialect-expression1} through @var{dialect-expression_@var{n}}
4321 @item (nor @var{dialect-expression1} @dots{} @var{dialect-expression_@var{n}})
4322 For complement of the union sets of dialects corresponding to
4323 @var{dialect-expression1} through @var{dialect-expression_@var{n}}
4324 relatively to the set of all supported dialects
4325 @item (not @var{dialect-expr})
4326 For complement set of dialect corresponding to @var{dialect-expr}
4327 relatively to the set of all supported dialects
4333 In case of adding a style hook for @LaTeX{}, when calling function
4334 @code{TeX-add-style-hook} it is thought more futureproof for argument
4335 @var{dialect-expr} to pass constant @code{LaTeX-dialect} currently
4336 defined to @code{:latex}, rather than passing @code{:latex} directly.
4338 @defvr Constant LaTeX-dialect
4339 Default dialect for use with function @code{TeX-add-style-hook} for
4340 argument @var{dialect-expr} when the hook is to be run only on LaTeX
4341 file, or any mode derived thereof.
4346 @subsection Adding Support for Macros
4347 @cindex Adding macros
4348 @cindex Macros, adding
4349 @cindex Defining macros in style hooks
4351 The most common thing to define in a style hook is new symbols (@TeX{}
4352 macros). Most likely along with a description of the arguments to the
4353 function, since the symbol itself can be defined automatically.
4355 Here are a few examples from @file{latex.el}.
4362 '("arabic" TeX-arg-counter)
4363 '("label" TeX-arg-define-label)
4364 '("ref" TeX-arg-ref)
4365 '("newcommand" TeX-arg-define-macro [ "Number of arguments" ] t)
4366 '("newtheorem" TeX-arg-define-environment
4367 [ TeX-arg-environment "Numbered like" ]
4368 t [ TeX-arg-counter "Within counter" ]))))
4371 @defun TeX-add-symbols @var{symbol} @dots{}
4372 Add each @var{symbol} to the list of known symbols.
4375 Each argument to @code{TeX-add-symbols} is a list describing one symbol.
4376 The head of the list is the name of the symbol, the remaining elements
4377 describe each argument.
4379 If there are no additional elements, the symbol will be inserted with
4380 point inside braces. Otherwise, each argument of this function should
4381 match an argument of the @TeX{} macro. What is done depends on the argument
4384 If a macro is defined multiple times, @AUCTeX{} will chose the one with
4385 the longest definition (i.e. the one with the most arguments).
4389 '("tref" 1) ; one argument
4393 '("tref" TeX-arg-ref ignore) ; two arguments
4396 @code{ignore} is a function that does not do anything, so when you
4397 insert a @samp{tref} you will be prompted for a label and no more.
4399 You can use the following types of specifiers for arguments:
4403 Use the string as a prompt to prompt for the argument.
4406 Insert that many braces, leave point inside the first. 0 and -1 are
4407 special. 0 means that no braces are inserted. -1 means that braces are
4408 inserted around the macro and an active region (e.g. @samp{@{\tiny
4409 foo@}}). If there is no active region, no braces are inserted.
4412 Insert empty braces.
4415 Insert empty braces, leave point between the braces.
4418 Call the symbol as a function. You can define your
4419 own hook, or use one of the predefined argument hooks.
4422 If the car is a string, insert it as a prompt and the next
4423 element as initial input. Otherwise, call the car of the list with
4424 the remaining elements as arguments.
4427 Optional argument. If it has more than one element, parse it
4428 as a list, otherwise parse the only element as above. Use square
4429 brackets instead of curly braces, and is not inserted on empty user
4433 A lot of argument hooks have already been defined. The first argument to
4434 all hooks is a flag indicating if it is an optional argument. It is up
4435 to the hook to determine what to do with the remaining arguments, if
4436 any. Typically the next argument is used to overwrite the default
4440 @item TeX-arg-conditional
4441 Implements if EXPR THEN ELSE. If EXPR evaluates to true, parse THEN as an
4442 argument list, else parse ELSE as an argument list.
4444 @item TeX-arg-literal
4445 Insert its arguments into the buffer. Used for specifying extra syntax
4449 Parse its arguments but use no braces when they are inserted.
4452 Evaluate arguments and insert the result in the buffer.
4455 Prompt for a label completing with known labels. If Ref@TeX{} is
4456 active, prompt for the reference format.
4459 Prompt for a label completing with known labels. If Ref@TeX{} is
4460 active, do not prompt for the reference format. Usually, reference
4461 macros should use this function instead of @code{TeX-arg-label}.
4463 @item TeX-arg-index-tag
4464 Prompt for an index tag. This is the name of an index, not the entry.
4467 Prompt for an index entry completing with known entries.
4469 @item TeX-arg-length
4470 Prompt for a @LaTeX{} length completing with known lengths.
4473 Prompt for a @TeX{} macro with completion.
4476 @vindex TeX-date-format
4477 Prompt for a date, defaulting to the current date. The format of the
4478 date is specified by the @code{TeX-date-format} option. If you want to
4479 change the format when the @samp{babel} package is loaded with a
4480 specific language, set @code{TeX-date-format} inside the appropriate
4481 language hook, for details @pxref{European}.
4483 @item TeX-arg-version
4484 Prompt for the version of a file, using as initial input the current
4487 @item TeX-arg-environment
4488 Prompt for a @LaTeX{} environment with completion.
4491 @vindex TeX-arg-cite-note-p
4492 Prompt for a Bib@TeX{} citation. If the variable
4493 @code{TeX-arg-cite-note-p} is non-nil, ask also for optional note in citations.
4495 @item TeX-arg-counter
4496 Prompt for a @LaTeX{} counter completing with known counters.
4498 @item TeX-arg-savebox
4499 Prompt for a @LaTeX{} savebox completing with known saveboxes.
4502 Prompt for a filename in the current directory, and use it without the
4505 @item TeX-arg-file-name
4506 Prompt for a filename and use as initial input the name of the file
4507 being visited in the current buffer, with extension.
4509 @item TeX-arg-file-name-sans-extension
4510 Prompt for a filename and use as initial input the name of the file
4511 being visited in the current buffer, without extension.
4513 @item TeX-arg-input-file
4514 @vindex TeX-arg-input-file-search
4515 Prompt for the name of an input file in @TeX{}'s search path, and use it
4516 without the extension. Run the style hooks for the file. (Note that
4517 the behavior (type of prompt and inserted file name) of the function can
4518 be controlled by the variable @code{TeX-arg-input-file-search}.)
4520 @item TeX-arg-define-label
4521 Prompt for a label completing with known labels. Add label to list of
4524 @item TeX-arg-define-length
4525 Prompt for a @LaTeX{} length completing with known lengths. Add length
4526 to list of defined lengths.
4529 @item TeX-arg-define-macro
4530 Prompt for a @TeX{} macro with completion. Add macro to list of defined
4533 @item TeX-arg-define-environment
4534 Prompt for a @LaTeX{} environment with completion. Add environment to
4535 list of defined environments.
4537 @item TeX-arg-define-cite
4538 Prompt for a Bib@TeX{} citation.
4540 @item TeX-arg-define-counter
4541 Prompt for a @LaTeX{} counter.
4543 @item TeX-arg-define-savebox
4544 Prompt for a @LaTeX{} savebox.
4546 @item TeX-arg-document
4547 @vindex LaTeX-default-style
4548 @vindex LaTeX-default-options
4549 @vindex TeX-arg-input-file-search
4550 @vindex LaTeX-style-list
4551 Prompt for a @LaTeX{} document class, using @code{LaTeX-default-style}
4552 as default value and @code{LaTeX-default-options} as default list of
4553 options. If the variable @code{TeX-arg-input-file-search} is t, you
4554 will be able to complete with all @LaTeX{} classes available on your
4555 system, otherwise classes listed in the variable @code{LaTeX-style-list}
4556 will be used for completion. It is also provided completion for options
4557 of many common classes.
4559 @item LaTeX-arg-usepackage
4560 @vindex TeX-arg-input-file-search
4561 Prompt for @LaTeX{} packages. If the variable
4562 @code{TeX-arg-input-file-search} is t, you will be able to complete with
4563 all @LaTeX{} packages available on your system. It is also provided
4564 completion for options of many common packages.
4566 @item TeX-arg-bibstyle
4567 Prompt for a Bib@TeX{} style file completing with all style available on
4570 @item TeX-arg-bibliography
4571 Prompt for BibTeX database files completing with all databases available
4574 @item TeX-arg-corner
4575 Prompt for a @LaTeX{} side or corner position with completion.
4578 Prompt for a @LaTeX{} side with completion.
4581 Prompt for a @LaTeX{} side with completion.
4583 @item TeX-arg-pagestyle
4584 Prompt for a @LaTeX{} pagestyle with completion.
4587 Prompt for delimiter and text.
4590 Insert a pair of numbers, use arguments for prompt. The numbers are
4591 surrounded by parentheses and separated with a comma.
4594 Insert width and height as a pair. No arguments.
4596 @item TeX-arg-coordinate
4597 Insert x and y coordinates as a pair. No arguments.
4599 @item LaTeX-arg-author
4600 @vindex LaTeX-default-author
4601 Prompt for document author, using @code{LaTeX-default-author} as initial
4604 @item TeX-read-key-val
4605 Prompt for a key=value list of options and return them.
4607 @item TeX-arg-key-val
4608 Prompt for a key=value list of options and insert it as a @TeX{} macro
4612 If you add new hooks, you can assume that point is placed directly after
4613 the previous argument, or after the macro name if this is the first
4614 argument. Please leave point located after the argument you are
4615 inserting. If you want point to be located somewhere else after all
4616 hooks have been processed, set the value of @code{exit-mark}. It will
4617 point nowhere, until the argument hook sets it.
4619 Some packages provide macros that are rarely useful to non-expert users.
4620 Those should be marked as expert macros using
4621 @code{TeX-declare-expert-macros}.
4623 @defun TeX-declare-expert-macros @var{style} @var{macros}...
4624 Declare MACROS as expert macros of STYLE.
4626 Expert macros are completed depending on `TeX-complete-expert-commands'.
4630 @node Adding Environments
4631 @subsection Adding Support for Environments
4632 @cindex Adding environments
4633 @cindex Environments, adding
4634 @cindex Defining environments in style hooks
4636 Adding support for environments is very much like adding support for
4637 @TeX{} macros, except that each environment normally only takes one
4638 argument, an environment hook. The example is again a short version of
4645 (LaTeX-add-environments
4646 '("document" LaTeX-env-document)
4647 '("enumerate" LaTeX-env-item)
4648 '("itemize" LaTeX-env-item)
4649 '("list" LaTeX-env-list))))
4652 It is completely up to the environment hook to insert the environment,
4653 but the function @code{LaTeX-insert-environment} may be of some help.
4654 The hook will be called with the name of the environment as its first
4655 argument, and extra arguments can be provided by adding them to a list
4658 For simple environments with arguments, for example defined with
4659 @samp{\newenvironment}, you can make @AUCTeX{} prompt for the arguments
4660 by giving the prompt strings in the call to
4661 @code{LaTeX-add-environments}. The fact that an argument is optional
4662 can be indicated by wrapping the prompt string in a vector.
4664 For example, if you have defined a @code{loop} environment with the
4665 three arguments @var{from}, @var{to}, and @var{step}, you can add
4666 support for them in a style file.
4671 \newenvironment@{loop@}[3]@{...@}@{...@}
4680 (LaTeX-add-environments
4681 '("loop" "From" "To" "Step"))))
4684 If an environment is defined multiple times, @AUCTeX{} will choose the
4685 one with the longest definition. Thus, if you have an enumerate style
4686 file, and want it to replace the standard @LaTeX{} enumerate hook above,
4687 you could define an @file{enumerate.el} file as follows, and place it in
4688 the appropriate style directory.
4694 (LaTeX-add-environments
4695 '("enumerate" LaTeX-env-enumerate foo))))
4697 (defun LaTeX-env-enumerate (environment &optional ignore) ...)
4700 The symbol @code{foo} will be passed to @code{LaTeX-env-enumerate} as
4701 the second argument, but since we only added it to overwrite the
4702 definition in @file{latex.el} it is just ignored.
4704 @defun LaTeX-add-environments @var{env} @dots{}
4705 Add each @var{env} to list of loaded environments.
4708 @defun LaTeX-insert-environment @var{env} [ @var{extra} ]
4709 Insert environment of type @var{env}, with optional argument @var{extra}.
4712 Following is a list of available hooks for
4713 @code{LaTeX-add-environments}:
4716 @item LaTeX-env-item
4717 Insert the given environment and the first item.
4719 @item LaTeX-env-figure
4720 Insert the given figure-like environment with a caption and a label.
4722 @item LaTeX-env-array
4723 Insert the given array-like environment with position and column
4726 @item LaTeX-env-label
4727 Insert the given environment with a label.
4729 @item LaTeX-env-list
4730 Insert the given list-like environment, a specifier for the label and
4733 @item LaTeX-env-minipage
4734 Insert the given minipage-like environment with position and width
4737 @item LaTeX-env-tabular*
4738 Insert the given tabular*-like environment with width, position and
4739 column specifications.
4741 @item LaTeX-env-picture
4742 Insert the given environment with width and height specifications.
4745 Insert the given environment with a label for a bibitem.
4747 @item LaTeX-env-contents
4748 Insert the given environment with a filename as its argument.
4750 @item LaTeX-env-args
4751 Insert the given environment with arguments. You can use this as a hook
4752 in case you want to specify multiple complex arguments just like in
4753 elements of @code{TeX-add-symbols}. This is most useful if the
4754 specification of arguments to be prompted for with strings and strings
4755 wrapped in a vector as described above is too limited.
4757 Here is an example from @file{listings.el} which calls a function with
4758 one argument in order to prompt for a key=value list to be inserted as
4759 an optional argument of the @samp{lstlisting} environment:
4762 (LaTeX-add-environments
4763 '("lstlisting" LaTeX-env-args
4764 [TeX-arg-key-val LaTeX-listings-key-val-options]))
4768 Some packages provide environments that are rarely useful to non-expert
4769 users. Those should be marked as expert environments using
4770 @code{LaTeX-declare-expert-environments}.
4772 @defun LaTeX-declare-expert-environments @var{style} @var{ENVIRONMENTS}...
4773 Declare ENVIRONMENTS as expert environments of STYLE.
4775 Expert environments are completed depending on `TeX-complete-expert-commands'.
4780 @subsection Adding Other Information
4781 @cindex Adding bibliographies
4782 @cindex Bibliographies, adding
4783 @cindex Defining bibliographies in style hooks
4784 @cindex Adding labels
4785 @cindex Labels, adding
4786 @cindex Defining labels in style hooks
4787 @cindex Adding other information
4788 @cindex Other information, adding
4789 @cindex Defining other information in style hooks
4791 You can also specify bibliographical databases and labels in the style
4792 file. This is probably of little use, since this information will
4793 usually be automatically generated from the @TeX{} file anyway.
4795 @defun LaTeX-add-bibliographies @var{bibliography} @dots{}
4796 Add each @var{bibliography} to list of loaded bibliographies.
4799 @defun LaTeX-add-labels @var{label} @dots{}
4800 Add each @var{label} to the list of known labels.
4803 @node Hacking the Parser
4804 @subsection Automatic Extraction of New Things
4805 @cindex Parsing new macros
4806 @cindex @file{macro.tex}
4807 @cindex @file{macro.el}
4808 @cindex Changing the parser
4810 The automatic @TeX{} information extractor works by searching for
4811 regular expressions in the @TeX{} files, and storing the matched
4812 information. You can add support for new constructs to the parser,
4813 something that is needed when you add new commands to define symbols.
4815 For example, in the file @file{macro.tex} I define the following macro.
4818 \newcommand@{\newmacro@}[5]@{%
4819 \def#1@{#3\index@{#4@@#5~cite@{#4@}@}\nocite@{#4@}@}%
4820 \def#2@{#5\index@{#4@@#5~cite@{#4@}@}\nocite@{#4@}@}%
4824 @AUCTeX{} will automatically figure out that @samp{newmacro} is a macro
4825 that takes five arguments. However, it is not smart enough to
4826 automatically see that each time we use the macro, two new macros are
4827 defined. We can specify this information in a style hook file.
4830 ;;; macro.el --- Special code for my own macro file.
4834 (defvar TeX-newmacro-regexp
4835 '("\\\\newmacro@{\\\\\\([a-zA-Z]+\\)@}@{\\\\\\([a-zA-Z]+\\)@}"
4836 (1 2) TeX-auto-multi)
4837 "Matches \newmacro definitions.")
4839 (defvar TeX-auto-multi nil
4840 "Temporary for parsing \\newmacro definitions.")
4842 (defun TeX-macro-cleanup ()
4843 "Move symbols from `TeX-auto-multi' to `TeX-auto-symbol'."
4844 (mapcar (lambda (list)
4845 (mapcar (lambda (symbol)
4846 (setq TeX-auto-symbol
4847 (cons symbol TeX-auto-symbol)))
4851 (defun TeX-macro-prepare ()
4852 "Clear `Tex-auto-multi' before use."
4853 (setq TeX-auto-multi nil))
4855 (add-hook 'TeX-auto-prepare-hook 'TeX-macro-prepare)
4856 (add-hook 'TeX-auto-cleanup-hook 'TeX-macro-cleanup)
4861 (TeX-auto-add-regexp TeX-newmacro-regexp)
4862 (TeX-add-symbols '("newmacro"
4864 (TeX-arg-macro "Capitalized macro: \\")
4869 ;;; macro.el ends here
4872 When this file is first loaded, it adds a new entry to
4873 @code{TeX-newmacro-regexp}, and defines a function to be called before
4874 the parsing starts, and one to be called after the parsing is done. It
4875 also declares a variable to contain the data collected during parsing.
4876 Finally, it adds a style hook which describes the @samp{newmacro} macro,
4877 as we have seen it before.
4879 So the general strategy is: Add a new entry to @code{TeX-newmacro-regexp}.
4880 Declare a variable to contain intermediate data during parsing. Add hook
4881 to be called before and after parsing. In this case, the hook before
4882 parsing just initializes the variable, and the hook after parsing
4883 collects the data from the variable, and adds them to the list of symbols
4886 @defvar TeX-auto-regexp-list
4887 List of regular expressions matching @TeX{} macro definitions.
4889 The list has the following format ((REGEXP MATCH TABLE) @dots{}), that
4890 is, each entry is a list with three elements.
4892 REGEXP. Regular expression matching the macro we want to parse.
4894 MATCH. A number or list of numbers, each representing one
4895 parenthesized subexpression matched by REGEXP.
4897 TABLE. The symbol table to store the data. This can be a function, in
4898 which case the function is called with the argument MATCH. Use
4899 @code{TeX-match-buffer} to get match data. If it is not a function, it
4900 is presumed to be the name of a variable containing a list of match
4901 data. The matched data (a string if MATCH is a number, a list of
4902 strings if MATCH is a list of numbers) is put in front of the table.
4905 @defvar TeX-auto-prepare-hook nil
4906 List of functions to be called before parsing a @TeX{} file.
4909 @defvar TeX-auto-cleanup-hook nil
4910 List of functions to be called after parsing a @TeX{} file.
4914 @appendix Copying, Changes, Development, FAQ, Texinfo Mode
4917 * Copying this Manual::
4924 @node Copying this Manual
4925 @appendixsec Copying this Manual
4928 The copyright notice for this manual is:
4933 The full license text can be read here:
4936 * GNU Free Documentation License:: License for copying this manual.
4944 @appendixsec Changes and New Features
4947 @include changes.texi
4950 @subheading Older versions
4951 See the file @file{history.texi} for older changes.
4954 @appendixsec Future Development
4961 @appendixsec Frequently Asked Questions
4968 @appendixsec Features specific to @AUCTeX{}'s Texinfo major mode
4970 @AUCTeX{} includes a major mode for editting Texinfo files. This major
4971 mode is not the same mode as the native Texinfo mode (@pxref{(texinfo)
4972 Texinfo Mode}) of Emacs, although they have the same name. However,
4973 @AUCTeX{} still relies on a number of functions from the native Texinfo
4976 The following text describes which functionality is offered by @AUCTeX{}
4977 and which by the native Texinfo mode. This should enable you to decide
4978 when to consult the @AUCTeX{} manual and when the manual of the native
4979 mode. And in case you are a seasoned user of the native mode, the
4980 information should help you to swiftly get to know the
4981 @AUCTeX{}-specific commands.
4984 * Exploiting:: How @AUCTeX{} and the native mode work together
4985 * Superseding:: Where the native mode is superseded
4986 * Mapping:: Where key bindings are mapped to the native mode
4987 * Unbinding:: Which native mode key bindings are missing
4991 @appendixsubsec How @AUCTeX{} and the native mode work together
4993 In a nutshell the split between @AUCTeX{} Texinfo mode, and native
4994 Texinfo mode is as follows:
4998 Most of the editing (environment creation, commenting, font command
4999 insertions) and/or processing commands (e.g. compiling or printing)
5000 which are available in other @AUCTeX{} modes are also handled by
5001 @AUCTeX{} in Texinfo mode.
5004 Texinfo-related features (e.g. info node linkage or menu creation) rely
5005 on the commands provided by the native Texinfo mode. @AUCTeX{} provides
5006 the key bindings to reach these functions, keeping the same keys as in
5007 native Texinfo whenever possible, or similar ones otherwise.
5011 @appendixsubsec Where the native mode is superseded
5013 This section is directed to users of the native Texinfo mode switching
5014 to @AUCTeX{}. It follows the summary of the native mode
5015 (@pxref{(texinfo) Texinfo Mode Summary}) and lists which of its commands
5016 are no longer of use.
5019 @item Insert commands
5020 In the native Texinfo mode, frequently used Texinfo commands can be
5021 inserted with key bindings of the form @kbd{C-c C-c @var{k}} where
5022 @var{k} differs for each Texinfo command; @kbd{c} inserts @@code,
5023 @kbd{d} inserts @@dfn, @kbd{k} @@kbd, etc.
5025 In @AUCTeX{} commands are inserted with the key binding @kbd{C-c C-m}
5026 instead which prompts for the macro to be inserted. For font selection
5027 commands (like @@b, @@i, or @@emph) and a few related ones (like @@var,
5028 @@key or @@code) there are bindings which insert the respective macros
5029 directly. They have the form @code{C-c C-f @var{k}} or @code{C-c C-f
5030 C-@var{k}} and call the function @code{TeX-font}. Type @kbd{C-c C-f
5031 @key{RET}} to get a list of supported commands.
5033 Note that the prefix argument is not handled the same way by @AUCTeX{}.
5034 Note also that the node insertion command from the native mode
5035 (@code{texinfo-insert-@@node}) can still accessed from the Texinfo menu
5039 In @AUCTeX{} braces can be inserted with the same key binding as in the
5040 native Texinfo mode: @kbd{C-c @{}. But @AUCTeX{} uses its own function
5041 for the feature: @code{TeX-insert-braces}.
5043 @item Insert environments
5044 The native Texinfo mode does not insert full environments. Instead, it
5045 provides the function @code{texinfo-insert-@@end} (mapped to @kbd{C-c
5046 C-c e}) for closing an open environment with a matching @@end statement.
5048 In @AUCTeX{} you can insert full environments, i.e. both the opening and
5049 closing statements, with the function @code{Texinfo-environment} (mapped
5052 @item Format info files with makeinfo and @TeX{}
5053 In the native Texinfo mode there are various functions and bindings to
5054 format a region or the whole buffer for info or to typeset the
5055 respective text. For example, there is @code{makeinfo-buffer} (mapped
5056 to @kbd{C-c C-m C-b}) which runs @samp{makeinfo} on the buffer or there
5057 is @code{texinfo-tex-buffer} (mapped to @kbd{C-c C-t C-b}) which runs
5058 @TeX{} on the buffer in order to produce a @acronym{DVI} file.
5060 In @AUCTeX{} different commands for formatting or typesetting can be
5061 invoked through the function @code{TeX-command-master} (mapped to
5062 @kbd{C-c C-c}). After typing @kbd{C-c C-c}, you can select the desired
5063 command, e.g @samp{Makeinfo} or @samp{TeX}, through a prompt in the mini
5064 buffer. Note that you can make, say @samp{Makeinfo}, the default by
5065 adding this statement in your init file:
5068 (add-hook 'Texinfo-mode-hook
5069 (lambda () (setq TeX-command-default "Makeinfo")))
5072 Note also that @kbd{C-c C-c Makeinfo @key{RET}} is not completely
5073 functionally equivalent to @code{makeinfo-buffer} as the latter will
5074 display the resulting info file in Emacs, showing the node corresponding
5075 to the position in the source file, just after a successful compilation.
5076 This is why, while using @AUCTeX{}, invoking @code{makeinfo-buffer}
5077 might still be more convenient.
5079 Note also that in the case of a multifile document, @kbd{C-c C-c} in
5080 @AUCTeX{} will work on the whole document (provided that the file
5081 variable @code{TeX-master} is set correctly), while
5082 @code{makeinfo-buffer} in the native mode will process only the current
5083 buffer, provided at the @code{@@setfilename} statement is provided.
5085 @item Produce indexes and print
5086 The native Texinfo mode provides the binding @kbd{C-c C-t C-i}
5087 (@code{texinfo-texindex}) for producing an index and the bindings
5088 @kbd{C-c C-t C-p} (@code{texinfo-tex-print}) and @kbd{C-c C-t C-q}
5089 (@code{tex-show-print-queue}) for printing and showing the printer
5090 queue. These are superseded by the respective commands available
5091 through @kbd{C-c C-c} (@code{TeX-command-master}) in @AUCTeX{}: Index,
5095 The command @kbd{C-c C-t C-k} (@code{tex-kill-job}) in the native mode
5096 is superseded by @kbd{C-c C-k} (@code{TeX-kill-job}) in @AUCTeX{}.
5100 @appendixsubsec Where key bindings are mapped to the native mode
5102 This node follows the native Texinfo mode summary (@pxref{(texinfo)
5103 Texinfo Mode Summary}) and lists only those commands to which @AUCTeX{}
5104 provides a keybinding.
5106 Basically all commands of the native mode related to producing menus and
5107 interlinking nodes are mapped to same or similar keys in @AUCTeX{},
5108 while a few insertion commands are mapped to @AUCTeX{}-like keys.
5112 @item @code{@@item} insertion
5113 The binding @kbd{C-c C-c i} for the insertion of @code{@@item} in the
5114 native mode is mapped to @kbd{M-@key{RET}} or @kbd{C-c C-j} in
5115 @AUCTeX{}, similar to other @AUCTeX{} modes.
5117 @item @code{@@end} insertion
5118 The binding @kbd{C-c C-c e} for closing a @code{@@@var{foo}} command by
5119 a corresponding @code{@@end @var{foo}} statement in the native mode is
5120 mapped to @kbd{C-c C-]} in @AUCTeX{}, similar to other @AUCTeX{} modes.
5122 @item Move out of balanced braces
5123 The binding @kbd{C-@}} (@code{up-list}) is available both in the native
5124 mode and in @AUCTeX{}. (This is because the command is not implemented
5125 in either mode but a native Emacs command.) However, in @AUCTeX{}, you
5126 cannot use @kbd{C-]} for this, as it is used for @code{@@end} insertion.
5128 @item Update pointers
5129 The bindings @kbd{C-c C-u C-n} (@code{texinfo-update-node}) and @kbd{C-c
5130 C-u C-e} (@code{texinfo-every-node-update}) from the native mode are
5131 available in @AUCTeX{} as well.
5134 The bindings @kbd{C-c C-u m} (@code{texinfo-master-menu}), @kbd{C-c C-u
5135 C-m} (@code{texinfo-make-menu}), and @kbd{C-c C-u C-a}
5136 (@code{texinfo-all-menus-update}) from the native mode are available in
5137 @AUCTeX{} as well. The command @code{texinfo-start-menu-description},
5138 bound to @kbd{C-c C-c C-d} in the native mode, is bound to @kbd{C-c C-u
5139 C-d} in @AUCTeX{} instead.
5143 @appendixsubsec Which native mode key bindings are missing
5145 The following commands from the native commands might still be useful
5146 when working with @AUCTeX{}, however, they are not accessible with a
5147 key binding any longer.
5150 @item @code{@@node} insertion
5151 The node insertion command, mapped to @kbd{C-c C-c n} in the native
5152 mode, is not mapped to any key in @AUCTeX{}. You can still access it
5153 through the Texinfo menu, though. Another alternative is to use the
5154 @kbd{C-c C-m} binding for macro insertion in @AUCTeX{}.
5156 @item Show the section structure
5157 The command @code{texinfo-show-structure} (@kbd{C-c C-s}) from the
5158 native mode does not have a key binding in @AUCTeX{}. The binding is
5159 used by @AUCTeX{} for sectioning.
5173 @unnumberedsec Key Index
5177 @node Function Index
5178 @unnumberedsec Function Index
5182 @node Variable Index
5183 @unnumberedsec Variable Index
5188 @unnumberedsec Concept Index