2 @comment %**start of header
3 @setfilename auctex.info
5 @settitle AUCTeX @value{VERSION}
6 @c footnotestyle separate
8 @comment %**end of header
11 This manual is for @AUCTeX{}
12 (version @value{VERSION} from @value{UPDATED}),
13 a sophisticated TeX environment for Emacs.
15 Copyright @copyright{} 1992, 1993, 1994, 1995, 2001, 2002, 2004, 2005,
16 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.3 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A
23 copy of the license is included in the section entitled ``GNU Free
24 Documentation License.''
30 * AUCTeX: (auctex). A sophisticated TeX environment for Emacs.
34 * AUCTeX: (auctex). A sophisticated TeX environment for Emacs.
38 @tolerance 10000 @emergencystretch 3em
44 @subtitle A sophisticated @TeX{} environment for Emacs
45 @subtitle Version @value{VERSION}, @value{UPDATED}
46 @author Kresten Krab Thorup
47 @author Per Abrahamsen
48 @author David Kastrup and others
50 @vskip 0pt plus 1filll
54 @c Use @ifinfo _and_ @ifhtml here because Texinfo 3 cannot cope with
55 @c @ifnottex around a top node.
60 This manual may be copied under the conditions spelled out in
61 @ref{Copying this Manual}.
73 @unnumbered Executive Summary
76 @AUCTeX{} is an integrated environment for editing @LaTeX{}, @ConTeXt{},
77 doc@TeX{}, Texinfo, and @TeX{} files.
79 Although @AUCTeX{} contains a large number of features, there are no
80 reasons to despair. You can continue to write @TeX{} and @LaTeX{}
81 documents the way you are used to, and only start using the multiple
82 features in small steps. @AUCTeX{} is not monolithic, each feature
83 described in this manual is useful by itself, but together they provide
84 an environment where you will make very few @LaTeX{} errors, and makes it
85 easy to find the errors that may slip through anyway.
87 It is a good idea to make a printout of @AUCTeX{}'s reference card
88 @file{tex-ref.tex} or one of its typeset versions.
90 If you want to make @AUCTeX{} aware of style files and multi-file
91 documents right away, insert the following in your @file{.emacs} file.
94 (setq TeX-auto-save t)
95 (setq TeX-parse-self t)
96 (setq-default TeX-master nil)
99 Another thing you should enable is Ref@TeX{}, a comprehensive solution
100 for managing cross references, bibliographies, indices, document
101 navigation and a few other things. (@pxref{Installation,,,reftex,The
104 For detailed information about the @previewlatex{} subsystem of
105 @AUCTeX{}, see @ref{Top,,Introduction,preview-latex,The @previewlatex{}
108 There is a mailing list for general discussion about @AUCTeX{}: write a
109 mail with ``subscribe'' in the subject to
110 @email{auctex-request@@gnu.org} to join it. Send contributions to
111 @email{auctex@@gnu.org}.
113 Bug reports should go to @email{bug-auctex@@gnu.org}, suggestions for
114 new features, and pleas for help should go to either
115 @email{auctex-devel@@gnu.org} (the @AUCTeX{} developers), or to
116 @email{auctex@@gnu.org} if they might have general interest. Please use
117 the command @kbd{M-x TeX-submit-bug-report RET} to report bugs if
118 possible. You can subscribe to a low-volume announcement list by
119 sending ``subscribe'' in the subject of a mail to
120 @email{info-auctex-request@@gnu.org}.
124 * Introduction:: Introduction to @AUCTeX{}
125 * Editing:: Editing the Document Source
126 * Display:: Controlling Screen Display
127 * Processing:: Starting Processors, Viewers and Other Programs
128 * Customization:: Customization and Extension
129 * Appendices:: Copying, Changes, Development, FAQ, 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
169 * Fontification of macros:: Fontification of macros
170 * Fontification of quotes:: Fontification of quotes
171 * Fontification of math:: Fontification of math constructs
172 * Verbatim content:: Verbatim macros and environments
173 * Faces:: Faces used by font-latex
175 Starting Processors, Viewers and Other Programs
177 * Commands:: Invoking external commands.
178 * Viewing:: Invoking external viewers.
179 * Debugging:: Debugging @TeX{} and @LaTeX{} output.
180 * Checking:: Checking the document.
181 * Control:: Controlling the processes.
182 * Cleaning:: Cleaning intermediate and output files.
183 * Documentation:: Documentation about macros and packages.
185 Viewing the Formatted Output
187 * Starting Viewers:: Starting viewers
188 * I/O Correlation:: Forward and inverse search
190 Customization and Extension
192 * Multifile:: Multifile Documents
193 * Parsing Files:: Automatic Parsing of @TeX{} Files
194 * Internationalization:: Language Support
195 * Automatic:: Automatic Customization
196 * Style Files:: Writing Your Own Style Support
200 * European:: Using @AUCTeX{} with European Languages
201 * Japanese:: Using @AUCTeX{} with Japanese
203 Automatic Customization
205 * Automatic Global:: Automatic Customization for the Site
206 * Automatic Private:: Automatic Customization for a User
207 * Automatic Local:: Automatic Customization for a Directory
209 Writing Your Own Style Support
211 * Simple Style:: A Simple Style File
212 * Adding Macros:: Adding Support for Macros
213 * Adding Environments:: Adding Support for Environments
214 * Adding Other:: Adding Other Information
215 * Hacking the Parser:: Automatic Extraction of New Things
217 Copying, Changes, Development, FAQ
219 * Copying this Manual::
227 * GNU Free Documentation License:: License for copying this manual.
244 @cindex General Public License
247 @cindex Free software
252 @c This text adapted from the Texinfo 2.16 distribution.
254 @AUCTeX{} primarily consists of Lisp files for Emacs (and XEmacs), but
255 there are also installation scripts and files and @TeX{} support files.
256 All of those are @dfn{free}; this means that everyone is free to use
257 them and free to redistribute them on a free basis. The files of
258 @AUCTeX{} are not in the public domain; they are copyrighted and there
259 are restrictions on their distribution, but these restrictions are
260 designed to permit everything that a good cooperating citizen would want
261 to do. What is not allowed is to try to prevent others from further
262 sharing any version of these programs that they might get from you.
264 Specifically, we want to make sure that you have the right to give away
265 copies of the files that constitute @AUCTeX{}, that you receive source
266 code or else can get it if you want it, that you can change these files
267 or use pieces of them in new free programs, and that you know you can do
270 To make sure that everyone has such rights, we have to forbid you to
271 deprive anyone else of these rights. For example, if you distribute
272 copies of parts of @AUCTeX{}, you must give the recipients all the
273 rights that you have. You must make sure that they, too, receive or can
274 get the source code. And you must tell them their rights.
276 Also, for our own protection, we must make certain that everyone finds
277 out that there is no warranty for @AUCTeX{}. If any parts are modified
278 by someone else and passed on, we want their recipients to know that
279 what they have is not what we distributed, so that any problems
280 introduced by others will not reflect on our reputation.
282 The precise conditions of the licenses for the files currently being
283 distributed as part of @AUCTeX{} are found in the General Public
284 Licenses that accompany them. This manual specifically is covered by
285 the GNU Free Documentation License (@pxref{Copying this Manual}).
288 @chapter Introduction
291 * Summary:: Overview of @AUCTeX{}
292 * Installation:: Installing @AUCTeX{}
293 * Quick Start:: Quick Start
299 @include install.texi
301 @include quickstart.texi
305 @chapter Editing the Document Source
307 The most commonly used commands/macros of @AUCTeX{} are those which
308 simply insert templates for often used @TeX{}, @LaTeX{}, or @ConTeXt{}
309 constructs, like font changes, handling of environments, etc. These
310 features are very simple, and easy to learn, and help you avoid mistakes
311 like mismatched braces, or @samp{\begin@{@}}-@samp{\end@{@}} pairs.
313 Apart from that this chapter contains a description of some features for
314 entering more specialized sorts of text, for formatting the source by
315 indenting and filling and for navigating through the document.
318 * Quotes:: Inserting double quotes
319 * Font Specifiers:: Inserting Font Specifiers
320 * Sectioning:: Inserting chapters, sections, etc.
321 * Environments:: Inserting Environment Templates
322 * Mathematics:: Entering Mathematics
323 * Completion:: Completion of macros
324 * Marking:: Marking Environments, Sections, or Texinfo Nodes
325 * Commenting:: Commenting text
326 * Indenting:: Reflecting syntactic constructs with whitespace
327 * Filling:: Automatic and manual line breaking
331 @section Insertion of Quotes, Dollars, and Braces
334 @cindex Double quotes
338 @cindex Math mode delimiters
339 @cindex Matching dollar signs
340 @cindex Display math mode
342 @subheading Quotation Marks
344 In @TeX{}, literal double quotes @samp{"like this"} are seldom used,
345 instead two single quotes are used @samp{``like this''}. To help you
346 insert these efficiently, @AUCTeX{} allows you to continue to press
347 @kbd{"} to insert two single quotes. To get a literal double quote,
350 @deffn Command TeX-insert-quote @var{count}
352 (@kbd{"}) Insert the appropriate quote marks for @TeX{}.
354 Inserts the value of @code{TeX-open-quote} (normally @samp{``}) or
355 @code{TeX-close-quote} (normally @samp{''}) depending on the context.
356 With prefix argument, always inserts @samp{"} characters.
359 @defopt TeX-open-quote
360 String inserted by typing @kbd{"} to open a quotation.
361 (@xref{European}, for language-specific quotation mark insertion.)
364 @defopt TeX-close-quote
365 String inserted by typing @kbd{"} to close a quotation.
366 (@xref{European}, for language-specific quotation mark insertion.)
369 @defopt TeX-quote-after-quote
370 Determines the behavior of @kbd{"}. If it is non-nil, typing @kbd{"}
371 will insert a literal double quote. The respective values of
372 @code{TeX-open-quote} and @code{TeX-close-quote} will be inserted
373 after typing @kbd{"} once again.
376 The @samp{babel} package provides special support for the requirements
377 of typesetting quotation marks in many different languages. If you use
378 this package, either directly or by loading a language-specific style
379 file, you should also use the special commands for quote insertion
380 instead of the standard quotes shown above. @AUCTeX{} is able to
381 recognize several of these languages and will change quote insertion
382 accordingly. @xref{European}, for details about this feature and how to
385 @vindex LaTeX-csquotes-open-quote
386 @vindex LaTeX-csquotes-close-quote
387 @vindex LaTeX-csquotes-quote-after-quote
388 In case you are using the @samp{csquotes} package, you should customize
389 @code{LaTeX-csquotes-open-quote}, @code{LaTeX-csquotes-close-quote} and
390 @code{LaTeX-csquotes-quote-after-quote}. The quotation characters will
391 only be used if both variables---@code{LaTeX-csquotes-open-quote} and
392 @code{LaTeX-csquotes-close-quote}---are non-empty strings. But then the
393 @samp{csquotes}-related values will take precedence over the
394 language-specific ones.
396 @subheading Dollar Signs
398 In @AUCTeX{}, dollar signs should match like they do in @TeX{}. This
399 has been partially implemented, we assume dollar signs always match
400 within a paragraph. The first @samp{$} you insert in a paragraph will
401 do nothing special. The second @samp{$} will match the first. This
402 will be indicated by moving the cursor temporarily over the first dollar
405 @deffn Command TeX-insert-dollar @var{arg}
407 (@kbd{$}) Insert dollar sign.
409 Show matching dollar sign if this dollar sign end the @TeX{} math mode.
410 Ensure double dollar signs match up correctly by inserting extra dollar
411 signs when needed if @code{TeX-math-close-double-dollar} is non-nil.
413 With optional @var{arg}, insert that many dollar signs.
416 @defopt TeX-math-close-double-dollar
417 Control the insertion of double dollar signs for delimiting display
418 math. (Note that you should not use double dollar signs in @LaTeX{}
419 because this practice can lead to wrong spacing in typeset documents.)
420 If the variable is non-nil and you enter a dollar sign that matches a
421 double dollar sign @samp{$$} @AUCTeX{} will automatically insert two
427 To avoid unbalanced braces, it is useful to insert them pairwise. You
428 can do this by typing @kbd{C-c @{}.
430 @deffn Command TeX-insert-braces
432 (@kbd{C-c @{}) Make a pair of braces and position the cursor
433 to type inside of them. If there is an active region, put braces around
434 it and leave point after the closing brace.
437 @node Font Specifiers
438 @section Inserting Font Specifiers
442 @cindex Changing font
443 @cindex Specifying a font
445 Perhaps the most used keyboard commands of @AUCTeX{} are the short-cuts
446 available for easy insertion of font changing macros.
448 If you give an argument (that is, type @kbd{C-u}) to the font command,
449 the innermost font will be replaced, i.e. the font in the @TeX{} group
450 around point will be changed. The following table shows the available
451 commands, with @code{@point{}} indicating the position where the text
457 @cindex @code{\textbf}
458 Insert @b{bold face} @samp{\textbf@{@point{}@}} text.
462 @cindex @code{\textit}
463 Insert @i{italics} @samp{\textit@{@point{}@}} text.
468 Insert @i{emphasized} @samp{\emph@{@point{}@}} text.
472 @cindex @code{\textsl}
473 Insert @i{slanted} @samp{\textsl@{@point{}@}} text.
477 @cindex @code{\textrm}
478 Insert roman @r{\textrm@{@point{}@}} text.
482 @cindex @code{\textsf}
483 Insert @sansserif{sans serif} @samp{\textsf@{@point{}@}} text.
487 @cindex @code{\texttt}
488 Insert @t{typewriter} @samp{\texttt@{@point{}@}} text.
492 @cindex @code{\textsc}
493 Insert @sc{small caps} @samp{\textsc@{@point{}@}} text.
497 @cindex Deleting fonts
498 Delete the innermost font specification containing point.
502 @deffn Command TeX-font replace what
504 (@kbd{C-c C-f}) Insert template for font change command.
506 If @var{replace} is not nil, replace current font. @var{what}
507 determines the font to use, as specified by @code{TeX-font-list}.
510 @defopt TeX-font-list
511 List of fonts used by @code{TeX-font}.
513 Each entry is a list with three elements. The first element is the
514 key to activate the font. The second element is the string to insert
515 before point, and the third element is the string to insert after
516 point. An optional fourth element means always replace if not nil.
519 @defopt LaTeX-font-list
520 List of fonts used by @code{TeX-font} in LaTeX mode. It has the same
521 structure as @code{TeX-font-list}.
525 @section Inserting chapters, sections, etc.
529 @cindex @code{\chapter}
530 @cindex @code{\section}
531 @cindex @code{\subsection}
532 @cindex @code{\label}
534 Insertion of sectioning macros, that is @samp{\chapter},
535 @samp{\section}, @samp{\subsection}, etc. and accompanying
536 @samp{\label}'s may be eased by using @kbd{C-c C-s}. This command is
537 highly customizable, the following describes the default behavior.
539 When invoking you will be asked for a section macro to insert. An
540 appropriate default is automatically selected by @AUCTeX{}, that is
541 either: at the top of the document; the top level sectioning for that
542 document style, and any other place: The same as the last occurring
545 Next, you will be asked for the actual name of that section, and
546 last you will be asked for a label to be associated with that section.
547 The label will be prefixed by the value specified in
548 @code{LaTeX-section-hook}.
550 @deffn Command LaTeX-section @var{arg}
552 (@kbd{C-c C-s}) Insert a sectioning command.
554 Determine the type of section to be inserted, by the argument
559 If @var{arg} is nil or missing, use the current level.
561 If @var{arg} is a list (selected by C-u), go downward one level.
563 If @var{arg} is negative, go up that many levels.
565 If @var{arg} is positive or zero, use absolute level:
584 The following variables can be set to customize the function.
587 @item LaTeX-section-hook
588 Hooks to be run when inserting a section.
589 @item LaTeX-section-label
590 Prefix to all section references.
595 The precise behavior of @code{LaTeX-section} is defined by the contents
596 of @code{LaTeX-section-hook}.
598 @defopt LaTeX-section-hook
599 List of hooks to run when a new section is inserted.
601 The following variables are set before the hooks are run
605 Numeric section level, default set by prefix arg to @code{LaTeX-section}.
607 Name of the sectioning command, derived from @var{level}.
609 The title of the section, default to an empty string.
611 Entry for the table of contents list, default nil.
613 Position of point afterwards, default nil meaning after the inserted
617 A number of hooks are already defined. Most likely, you will be able to
618 get the desired functionality by choosing from these hooks.
621 @item LaTeX-section-heading
622 Query the user about the name of the sectioning command. Modifies
623 @var{level} and @var{name}.
624 @item LaTeX-section-title
625 Query the user about the title of the section. Modifies @var{title}.
626 @item LaTeX-section-toc
627 Query the user for the toc entry. Modifies @var{toc}.
628 @item LaTeX-section-section
629 Insert @LaTeX{} section command according to @var{name}, @var{title},
630 and @var{toc}. If @var{toc} is nil, no toc entry is inserted. If
631 @var{toc} or @var{title} are empty strings, @var{done-mark} will be
632 placed at the point they should be inserted.
633 @item LaTeX-section-label
634 Insert a label after the section command. Controlled by the variable
635 @code{LaTeX-section-label}.
638 To get a full featured @code{LaTeX-section} command, insert
641 (setq LaTeX-section-hook
642 '(LaTeX-section-heading
645 LaTeX-section-section
646 LaTeX-section-label))
649 in your @file{.emacs} file.
652 The behavior of @code{LaTeX-section-label} is determined by the
653 variable @code{LaTeX-section-label}.
655 @defopt LaTeX-section-label
656 Default prefix when asking for a label.
658 If it is a string, it is used unchanged for all kinds of sections.
659 If it is nil, no label is inserted.
660 If it is a list, the list is searched for a member whose car is equal
661 to the name of the sectioning command being inserted. The cdr is then
662 used as the prefix. If the name is not found, or if the cdr is nil,
663 no label is inserted.
665 @cindex Prefix for labels
668 By default, chapters have a prefix of @samp{cha:} while sections and
669 subsections have a prefix of @samp{sec:}. Labels are not automatically
670 inserted for other types of sections.
674 @section Inserting Environment Templates
676 @cindex @samp{\begin}
679 A large apparatus is available that supports insertions of environments,
680 that is @samp{\begin@{@}} --- @samp{\end@{@}} pairs.
682 @AUCTeX{} is aware of most of the actual environments available in a
683 specific document. This is achieved by examining your
684 @samp{\documentclass} command, and consulting a precompiled list of
685 environments available in a large number of styles.
687 You insert an environment with @kbd{C-c C-e}, and select an environment
688 type. Depending on the environment, @AUCTeX{} may ask more questions
689 about the optional parts of the selected environment type. With
690 @kbd{C-u C-c C-e} you will change the current environment.
692 @deffn Command LaTeX-environment @var{arg}
694 (@kbd{C-c C-e}) @AUCTeX{} will prompt you for an environment
695 to insert. At this prompt, you may press @key{TAB} or @key{SPC} to
696 complete a partially written name, and/or to get a list of available
697 environments. After selection of a specific environment @AUCTeX{} may
698 prompt you for further specifications.
700 If the optional argument @var{arg} is not-nil (i.e. you have given a
701 prefix argument), the current environment is modified and no new
702 environment is inserted.
705 As a default selection, @AUCTeX{} will suggest the environment last
706 inserted or, as the first choice the value of the variable
707 @code{LaTeX-default-environment}.
709 @defopt LaTeX-default-environment
710 Default environment to insert when invoking @samp{LaTeX-environment}
714 If the document is empty, or the cursor is placed at the top of the
715 document, @AUCTeX{} will default to insert a `document' environment.
717 Most of these are described further in the following sections, and you
718 may easily specify more. @xref{Customizing Environments}.
721 * Equations:: Equations
723 * Itemize-like:: Itemize-like Environments
724 * Tabular-like:: Tabular-like Environments
725 * Customizing Environments:: Customizing Environments
728 You can close the current environment with @kbd{C-c ]}, but we suggest
729 that you use @kbd{C-c C-e} to insert complete environments instead.
731 @deffn Command LaTeX-close-environment
733 (@kbd{C-c ]}) Insert an @samp{\end} that matches the current environment.
737 @subsection Equations
743 When inserting equation-like environments, the @samp{\label} will have a
744 default prefix, which is controlled by the following variables:
746 @defopt LaTeX-equation-label
747 Prefix to use for `equation' labels.
750 @defopt LaTeX-eqnarray-label
751 Prefix to use for `eqnarray' labels.
754 @defopt LaTeX-amsmath-label
755 Prefix to use for amsmath equation labels. Amsmath equations include
756 @samp{align}, @samp{alignat}, @samp{xalignat}, @samp{aligned},
757 @samp{flalign} and @samp{gather}.
764 @cindex Figure environment
766 @cindex Table environment
768 Figures and tables (i.e., floats) may also be inserted using @AUCTeX{}.
769 After choosing either `figure' or `table' in the environment list
770 described above, you will be prompted for a number of additional things.
774 This is the optional argument of float environments that controls how
775 they are placed in the final document. In @LaTeX{} this is a sequence
776 of the letters @samp{htbp} as described in the @LaTeX{} manual. The
777 value will default to the value of @code{LaTeX-float}.
781 This is the caption of the float. The default is to insert the caption
782 at the bottom of the float. You can specify floats where the caption
783 should be placed at the top with @code{LaTeX-top-caption-list}.
784 @vindex LaTeX-top-caption-list
787 The label of this float. The label will have a default prefix, which is
788 controlled by the variables @code{LaTeX-figure-label} and
789 @code{LaTeX-table-label}.
790 @vindex LaTeX-figure-label
791 @vindex LaTeX-table-label
792 @cindex Prefix for labels
797 Moreover, you will be asked if you want the contents of the float
798 environment to be horizontally centered. Upon a positive answer a
799 @samp{\centering} macro will be inserted at the beginning of the float
803 Default placement for floats.
806 @defopt LaTeX-figure-label
807 Prefix to use for figure labels.
810 @defopt LaTeX-table-label
811 Prefix to use for table labels.
814 @defopt LaTeX-top-caption-list
815 List of float environments with top caption.
819 @subsection Itemize-like Environments
826 In an itemize-like environment, nodes (i.e., @samp{\item}s) may be
827 inserted using @kbd{C-c @key{LFD}}.
829 @deffn Command LaTeX-insert-item
830 @kindex C-c @key{LFD}
831 (@kbd{C-c @key{LFD}}) Close the current item, move to the next line and
832 insert an appropriate @samp{\item} for the current environment. That is,
833 `itemize' and `enumerate' will have @samp{\item } inserted, while
834 `description' will have @samp{\item[]} inserted.
838 @subsection Tabular-like Environments
840 When inserting Tabular-like environments, that is, `tabular' `array'
841 etc., you will be prompted for a template for that environment.
844 @defopt LaTeX-default-format
845 Default format string for array and tabular environments.
848 @defopt LaTeX-default-position
849 Default position string for array and tabular environments. If nil,
850 act like the empty string is given, but don't prompt for a position.
853 @node Customizing Environments
854 @subsection Customizing Environments
856 @xref{Adding Environments}, for how to customize the list of known
860 @section Entering Mathematics
863 @cindex Abbreviations
865 @TeX{} is written by a mathematician, and has always contained good
866 support for formatting mathematical text. @AUCTeX{} supports this
867 tradition, by offering a special minor mode for entering text with many
868 mathematical symbols. You can enter this mode by typing @kbd{C-c
871 @deffn Command LaTeX-math-mode
873 (@kbd{C-c ~}) Toggle LaTeX Math mode. This is a minor mode rebinding
874 the key @code{LaTeX-math-abbrev-prefix} to allow easy typing of
875 mathematical symbols. @kbd{`} will read a character from the keyboard,
876 and insert the symbol as specified in @code{LaTeX-math-default} and
877 @code{LaTeX-math-list}. If given a prefix argument, the symbol will be
878 surrounded by dollar signs.
881 You can use another prefix key (instead of @kbd{`}) by setting the
882 variable @code{LaTeX-math-abbrev-prefix}.
884 To enable LaTeX Math mode by default, add the following in your
887 (add-hook 'LaTeX-mode-hook 'LaTeX-math-mode)
890 @defopt LaTeX-math-abbrev-prefix
891 A string containing the prefix of @code{LaTeX-math-mode} commands; This
892 value defaults to @kbd{`}.
894 The string has to be a key or key sequence in a format understood by the
895 @code{kbd} macro. This corresponds to the syntax usually used in the
896 manuals for Emacs Emacs Lisp.
899 The variable @code{LaTeX-math-list} allows you to add your own mappings.
901 @defopt LaTeX-math-list
902 A list containing user-defined keys and commands to be used in LaTeX
903 Math mode. Each entry should be a list of two to four elements.
905 First, the key to be used after @code{LaTeX-math-abbrev-prefix} for
906 macro insertion. If it is nil, the symbol has no associated
907 keystroke (it is available in the menu, though).
909 Second, a string representing the name of the macro (without a leading
912 Third, a string representing the name of a submenu the command should be
913 added to. Use a list of strings in case of nested menus.
915 Fourth, the position of a Unicode character to be displayed in the menu
916 alongside the macro name. This is an integer value.
919 @defopt LaTeX-math-menu-unicode
920 Whether the LaTeX menu should try using Unicode for effect. Your Emacs
921 built must be able to display include Unicode characters in menus for
925 @AUCTeX{}'s reference card @file{tex-ref.tex} includes a list of all
928 @AUCTeX{} can help you write subscripts and superscripts in math
929 constructs by automatically inserting a pair of braces after typing
930 @key{_} or @key{^} respectively and putting point between the braces.
931 In order to enable this feature, set the variable
932 @code{TeX-electric-sub-and-superscript} to a non-nil value.
934 @defopt TeX-electric-sub-and-superscript
935 If non-nil, insert braces after typing @key{^} and @key{_} in math mode.
942 @cindex Macro expansion
943 @cindex Macro completion
944 @cindex Macro arguments
945 @cindex Arguments to @TeX{} macros
947 Emacs lisp programmers probably know the @code{lisp-complete-symbol}
948 command, usually bound to @kbd{M-@key{TAB}}. Users of the wonderful
949 ispell mode know and love the @code{ispell-complete-word} command from
950 that package. Similarly, @AUCTeX{} has a @code{TeX-complete-symbol}
951 command, by default bound to @kbd{M-@key{TAB}} which is equivalent to
952 @kbd{M-C-i}. Using @code{TeX-complete-symbol} makes it easier to type
953 and remember the names of long @LaTeX{} macros.
955 In order to use @code{TeX-complete-symbol}, you should write a backslash
956 and the start of the macro. Typing @kbd{M-@key{TAB}} will now complete
957 as much of the macro, as it unambiguously can. For example, if you type
958 `@samp{\renewc}' and then @kbd{M-@key{TAB}}, it will expand to
959 `@samp{\renewcommand}'.
961 @deffn Command TeX-complete-symbol
963 (@kbd{M-@key{TAB}}) Complete @TeX{} symbol before point.
966 A more direct way to insert a macro is with @code{TeX-insert-macro},
967 bound to @kbd{C-c C-m} which is equivalent to @kbd{C-c @key{RET}}. It
968 has the advantage over completion that it knows about the argument of
969 most standard @LaTeX{} macros, and will prompt for them. It also knows
970 about the type of the arguments, so it will for example give completion
971 for the argument to @samp{\include}. Some examples are listed below.
973 @deffn Command TeX-insert-macro
975 (@kbd{C-c C-m} or @kbd{C-c @key{RET}}) Prompt (with completion) for the
976 name of a @TeX{} macro, and if @AUCTeX{} knows the macro, prompt for
980 As a default selection, @AUCTeX{} will suggest the macro last inserted
981 or, as the first choice the value of the variable
982 @code{TeX-default-macro}.
984 @defopt TeX-insert-macro-default-style
985 Specifies whether @code{TeX-insert-macro} will ask for all optional
988 If set to the symbol @code{show-optional-args}, @code{TeX-insert-macro}
989 asks for optional arguments of @TeX{} macros. If set to
990 @code{mandatory-args-only}, @code{TeX-insert-macro} asks only for
991 mandatory arguments. When @code{TeX-insert-macro} is called with prefix
992 argument (@kbd{C-u}), it's the other way round.
994 Note that for some macros, there are special mechanisms, e.g.
995 @code{LaTeX-includegraphics-options-alist}.
1000 @defopt TeX-default-macro
1001 Default macro to insert when invoking @code{TeX-insert-macro} first time.
1004 A faster alternative is to bind the function @code{TeX-electric-macro}
1005 to @samp{\}. This can be done by setting the variable
1006 @code{TeX-electric-escape}
1008 @defopt TeX-electric-escape
1009 If this is non-nil when @AUCTeX{} is loaded, the @TeX{} escape
1010 character @samp{\} will be bound to @code{TeX-electric-macro}
1013 The difference between @code{TeX-insert-macro} and
1014 @code{TeX-electric-macro} is that space will complete and exit from the
1015 minibuffer in @code{TeX-electric-macro}. Use @key{TAB} if you merely
1018 @deffn Command TeX-electric-macro
1019 Prompt (with completion) for the name of a @TeX{} macro,
1020 and if @AUCTeX{} knows the macro, prompt for each argument.
1021 Space will complete and exit.
1024 By default @AUCTeX{} will put an empty set braces @samp{@{@}} after a
1025 macro with no arguments to stop it from eating the next whitespace.
1026 This can be stopped by entering @code{LaTeX-math-mode},
1027 @pxref{Mathematics}, or by setting @code{TeX-insert-braces} to nil.
1029 @defopt TeX-insert-braces
1030 If non-nil, append a empty pair of braces after inserting a macro.
1033 Completions work because @AUCTeX{} can analyze @TeX{} files, and store
1034 symbols in Emacs Lisp files for later retrieval. @xref{Automatic}, for
1037 @cindex \cite, completion of
1038 @cindex Bib@TeX{}, completion
1039 @cindex cite, completion of
1040 @cindex bibliography, completion
1041 @cindex citations, completion of
1042 @cindex \label, completion
1043 @cindex \ref, completion
1044 @cindex labels, completion of
1045 @AUCTeX{} will also make completion for many macro arguments, for
1046 example existing labels when you enter a @samp{\ref} macro with
1047 @code{TeX-insert-macro} or @code{TeX-electric-macro}, and Bib@TeX{}
1048 entries when you enter a @samp{\cite} macro. For this kind of
1049 completion to work, parsing must be enabled as described in
1050 @pxref{Parsing Files}. For @samp{\cite} you must also make sure that
1051 the Bib@TeX{} files have been saved at least once after you enabled
1052 automatic parsing on save, and that the basename of the Bib@TeX{} file
1053 does not conflict with the basename of one of @TeX{} files.
1056 @section Marking Environments, Sections, or Texinfo Nodes
1058 You can mark the current environment by typing @kbd{C-c .}, or the
1059 current section by typing @kbd{C-c *}.
1061 In Texinfo documents you can type @kbd{M-C-h} to mark the current node.
1063 When the region is set, the point is moved to its beginning and the mark
1067 * Marking (LaTeX):: LaTeX Commands for Marking Environments and Sections
1068 * Marking (Texinfo):: Texinfo Commands for Marking Environments, Sections, and Nodes
1071 @node Marking (LaTeX)
1072 @subsection LaTeX Commands for Marking Environments and Sections
1074 @deffn Command LaTeX-mark-section
1076 (@kbd{C-c *}) Set mark at end of current logical section, and point at
1079 With a non-nil prefix argument, mark only the region from the current
1080 section start to the next sectioning command. Thereby subsections are
1081 not being marked. Otherwise, any included subsections are also marked
1082 along with current section.
1085 @deffn Command LaTeX-mark-environment
1087 (@kbd{C-c .}) Set mark to the end of the current environment and point
1088 to the matching beginning.
1090 If a prefix argument is given, mark the respective number of enclosing
1091 environments. The command will not work properly if there are
1092 unbalanced begin-end pairs in comments and verbatim environments.
1095 @node Marking (Texinfo)
1096 @subsection Texinfo Commands for Marking Environments and Sections
1098 @deffn Command Texinfo-mark-section
1100 (@kbd{C-c *}) Mark the current section, with inclusion of any containing
1103 The current section is detected as starting by any of the structuring
1104 commands matched by the regular expression in the variable
1105 @code{outline-regexp} which in turn is a regular expression matching any
1106 element of the variable @code{texinfo-section-list}.
1108 With a non-nil prefix argument, mark only the region from the current
1109 section start to the next sectioning command. Thereby subsections are
1110 not being marked. Otherwise, any included subsections are also marked
1112 Note that when the current section is starting immediately after a node
1113 command, then the node command is also marked as part of the section.
1116 @deffn Command Texinfo-mark-environment
1118 (@kbd{C-c .}) Set mark to the end of the current environment and point
1119 to the matching beginning.
1121 If a prefix argument is given, mark the respective number of enclosing
1122 environments. The command will not work properly if there are
1123 unbalanced begin-end pairs in comments and verbatim environments.
1126 @deffn Command Texinfo-mark-node
1128 (@kbd{M-C-h}) Mark the current node. This is the node in which point is
1129 located. It is starting at the previous occurrence of the keyword
1130 @code{@@node} and ending at next occurrence of the keywords
1131 @code{@@node} or @code{@@bye}.
1137 It is often necessary to comment out temporarily a region of @TeX{} or
1138 @LaTeX{} code. This can be done with the commands @kbd{C-c ;} and
1139 @kbd{C-c %}. @kbd{C-c ;} will comment out all lines in the current
1140 region, while @kbd{C-c %} will comment out the current paragraph.
1141 Type @kbd{C-c ;} again to uncomment all lines of a commented region,
1142 or @kbd{C-c %} again to uncomment all comment lines around point.
1143 These commands will insert or remove a single @samp{%} respectively.
1145 @deffn Command TeX-comment-or-uncomment-region
1147 (@kbd{C-c ;}) Add or remove @samp{%} from the beginning of each line
1148 in the current region. Uncommenting works only if the region encloses
1149 solely commented lines. If @AUCTeX{} should not try to guess if the
1150 region should be commented or uncommented the commands
1151 @code{TeX-comment-region} and @code{TeX-uncomment-region} can be used
1152 to explicitly comment or uncomment the region in concern.
1155 @deffn Command TeX-comment-or-uncomment-paragraph
1157 (@kbd{C-c %}) Add or remove @samp{%} from the beginning of each line
1158 in the current paragraph. When removing @samp{%} characters the
1159 paragraph is considered to consist of all preceding and succeeding
1160 lines starting with a @samp{%}, until the first non-comment line.
1168 @cindex Reformatting
1171 Indentation means the addition of whitespace at the beginning of lines
1172 to reflect special syntactical constructs. This makes it easier to see
1173 the structure of the document, and to catch errors such as a missing
1174 closing brace. Thus, the indentation is done for precisely the same
1175 reasons that you would indent ordinary computer programs.
1177 Indentation is done by @LaTeX{} environments and by @TeX{} groups, that
1178 is the body of an environment is indented by the value of
1179 @code{LaTeX-indent-level} (default 2). Also, items of an `itemize-like'
1180 environment are indented by the value of @code{LaTeX-item-indent},
1181 default @minus{}2. (Items are identified with the help of
1182 @code{LaTeX-item-regexp}.) If more environments are nested, they are
1183 indented `accumulated' just like most programming languages usually are
1184 seen indented in nested constructs.
1185 @vindex LaTeX-indent-level
1186 @vindex LaTeX-item-indent
1187 @vindex LaTeX-item-regexp
1189 You can explicitely indent single lines, usually by pressing @key{TAB},
1190 or marked regions by calling @code{indent-region} on it. If you have
1191 @code{auto-fill-mode} enabled and a line is broken while you type it,
1192 Emacs automatically cares about the indentation in the following line.
1193 If you want to have a similar behavior upon typing @key{RET}, you can
1194 customize the variable @code{TeX-newline-function} and change the
1195 default of @code{newline} which does no indentation to
1196 @code{newline-and-indent} which indents the new line or
1197 @code{reindent-then-newline-and-indent} which indents both the current
1199 @vindex TeX-newline-function
1201 There are certain @LaTeX{} environments which should be indented in a
1202 special way, like @samp{tabular} or @samp{verbatim}. Those environments
1203 may be specified in the variable @code{LaTeX-indent-environment-list}
1204 together with their special indentation functions. Taking the
1205 @samp{verbatim} environment as an example you can see that
1206 @code{current-indentation} is used as the indentation function. This
1207 will stop @AUCTeX{} from doing any indentation in the environment if you
1208 hit @key{TAB} for example.
1209 @vindex LaTeX-indent-environment-list
1211 There are environments in @code{LaTeX-indent-environment-list} which do
1212 not bring a special indentation function with them. This is due to the
1213 fact that first the respective functions are not implemented yet and
1214 second that filling will be disabled for the specified environments.
1215 This shall prevent the source code from being messed up by accidently
1216 filling those environments with the standard filling routine. If you
1217 think that providing special filling routines for such environments
1218 would be an appropriate and challenging task for you, you are invited to
1219 contribute. (@xref{Filling}, for further information about the filling
1221 @vindex LaTeX-indent-environment-list
1223 The check for the indentation function may be enabled or disabled by
1224 customizing the variable @code{LaTeX-indent-environment-check}.
1225 @vindex LaTeX-indent-environment-check
1227 As a side note with regard to formatting special environments: Newer
1228 Emacsen include @file{align.el} and therefore provide some support for
1229 formatting @samp{tabular} and @samp{tabbing} environments with the
1230 function @code{align-current} which will nicely align columns in the
1233 @AUCTeX{} is able to format commented parts of your code just as any
1234 other part. This means @LaTeX{} environments and @TeX{} groups in
1235 comments will be indented syntactically correct if the variable
1236 @code{LaTeX-syntactic-comments} is set to t. If you disable it,
1237 comments will be filled like normal text and no syntactic indentation
1239 @vindex LaTeX-syntactic-comments
1241 Following you will find a list of most commands and variables related
1242 to indenting with a small summary in each case:
1247 @findex LaTeX-indent-line
1248 @code{LaTeX-indent-line} will indent the current line.
1252 @code{newline-and-indent} inserts a new line (much like @key{RET}) and
1253 moves the cursor to an appropriate position by the left margin.
1255 Most keyboards nowadays lack a linefeed key and @kbd{C-j} may be tedious
1256 to type. Therefore you can customize @AUCTeX{} to perform indentation
1257 upon typing @key{RET} as well. The respective option is called
1258 @code{TeX-newline-function}.
1265 @defopt LaTeX-indent-environment-list
1266 List of environments with special indentation. The second element in
1267 each entry is the function to calculate the indentation level in
1270 The filling code currently cannot handle tabular-like environments
1271 which will be completely messed-up if you try to format them. This is
1272 why most of these environments are included in this customization
1273 option without a special indentation function. This will prevent that
1277 @defopt LaTeX-indent-level
1278 Number of spaces to add to the indentation for each @samp{\begin} not
1279 matched by a @samp{\end}.
1282 @defopt LaTeX-item-indent
1283 Number of spaces to add to the indentation for @samp{\item}'s in list
1287 @defopt TeX-brace-indent-level
1288 Number of spaces to add to the indentation for each @samp{@{} not
1289 matched by a @samp{@}}.
1292 @defopt LaTeX-syntactic-comments
1293 If non-nil comments will be filled and indented according to @LaTeX{}
1294 syntax. Otherwise they will be filled like normal text.
1297 @defopt TeX-newline-function
1298 Used to specify the function which is called when @key{RET} is pressed.
1299 This will normally be @code{newline} which simply inserts a new line.
1300 In case you want to have @AUCTeX{} do indentation as well when you press
1301 @key{RET}, use the built-in functions @code{newline-and-indent} or
1302 @code{reindent-then-newline-and-indent}. The former inserts a new line
1303 and indents the following line, i.e. it moves the cursor to the right
1304 position and therefore acts as if you pressed @key{LFD}. The latter
1305 function additionally indents the current line. If you choose
1306 @samp{Other}, you can specify your own fancy function to be called when
1307 @key{RET} is pressed.
1315 @cindex Reformatting
1318 Filling deals with the insertion of line breaks to prevent lines from
1319 becoming wider than what is specified in @code{fill-column}. The
1320 linebreaks will be inserted automatically if @code{auto-fill-mode} is
1321 enabled. In this case the source is not only filled but also indented
1322 automatically as you write it.
1324 @code{auto-fill-mode} can be enabled for @AUCTeX{} by calling
1325 @code{turn-on-auto-fill} in one of the hooks @AUCTeX{} is running.
1326 @xref{Modes and Hooks}. As an example, if you want to enable
1327 @code{auto-fill-mode} in @code{LaTeX-mode}, put the following into your
1331 (add-hook 'LaTeX-mode-hook 'turn-on-auto-fill)
1334 You can manually fill explicitely marked regions, paragraphs,
1335 environments, complete sections, or the whole buffer. (Note that manual
1336 filling in @AUCTeX{} will indent the start of the region to be filled in
1337 contrast to many other Emacs modes.)
1339 There are some syntactical constructs which are handled specially with
1340 regard to filling. These are so-called code comments and paragraph
1343 Code comments are comments preceded by code or text in the same line.
1344 Upon filling a region, code comments themselves will not get filled.
1345 Filling is done from the start of the region to the line with the code
1346 comment and continues after it. In order to prevent overfull lines in
1347 the source code, a linebreak will be inserted before the last
1348 non-comment word by default. This can be changed by customizing
1349 @code{LaTeX-fill-break-before-code-comments}. If you have overfull
1350 lines with code comments you can fill those explicitely by calling
1351 @code{LaTeX-fill-paragraph} or pressing @kbd{M-q} with the cursor
1352 positioned on them. This will add linebreaks in the comment and indent
1353 subsequent comment lines to the column of the comment in the first line
1354 of the code comment. In this special case @kbd{M-q} only acts on the
1355 current line and not on the whole paragraph.
1357 Lines with @samp{\par} are treated similarly to code comments,
1358 i.e. @samp{\par} will be treated as paragraph boundary which should not
1359 be followed by other code or text. But it is not treated as a real
1360 paragraph boundary like an empty line where filling a paragraph would
1363 Paragraph commands like @samp{\section} or @samp{\noindent} (the list of
1364 commands is defined by @code{LaTeX-paragraph-commands}) are often to be
1365 placed in their own line(s). This means they should not be consecuted
1366 with any preceding or following adjacent lines of text. @AUCTeX{} will
1367 prevent this from happening if you do not put any text except another
1368 macro after the end of the last brace of the respective macro. If
1369 there is other text after the macro, @AUCTeX{} regards this as a sign
1370 that the macro is part of the following paragraph.
1371 @vindex LaTeX-paragraph-commands
1373 Here are some examples:
1381 \begin@{quote@}\label@{foo@}
1385 If you press @kbd{M-q} on the first line in both examples, nothing will
1386 change. But if you write
1389 \begin@{quote@} text
1393 and press @kbd{M-q}, you will get
1396 \begin@{quote@} text text text text text
1399 Besides code comments and paragraph commands, another speciality of
1400 filling in @AUCTeX{} involves commented lines. You should be aware that
1401 these comments are treated as islands in the rest of the @LaTeX{} code
1402 if syntactic filling is enabled. This means, for example, if you try to
1403 fill an environment with @code{LaTeX-fill-environment} and have the
1404 cursor placed on a commented line which does not have a surrounding
1405 environment inside the comment, @AUCTeX{} will report an error.
1406 @findex LaTeX-fill-environment
1408 The relevant commands and variables with regard to filling are:
1413 @findex LaTeX-fill-paragraph
1414 @code{LaTeX-fill-paragraph} will fill and indent the current paragraph.
1418 Alias for @kbd{C-c C-q C-p}
1422 @findex LaTeX-fill-environment
1423 @code{LaTeX-fill-environment} will fill and indent the current
1424 environment. This may e.g. be the `document' environment, in which case
1425 the entire document will be formatted.
1429 @findex LaTeX-fill-section
1430 @code{LaTeX-fill-section} will fill and indent the current logical
1435 @findex LaTeX-fill-region
1436 @code{LaTeX-fill-region} will fill and indent the current region.
1439 @defopt LaTeX-fill-break-at-separators
1440 List of separators before or after which respectively linebreaks will
1441 be inserted if they do not fit into one line. The separators can be
1442 curly braces, brackets, switches for inline math (@samp{$}, @samp{\(},
1443 @samp{\)}) and switches for display math (@samp{\[}, @samp{\]}). Such
1444 formatting can be useful to make macros and math more visible or to
1445 prevent overfull lines in the @LaTeX{} source in case a package for
1446 displaying formatted @TeX{} output inside the Emacs buffer, like
1447 preview-latex, is used.
1450 @defopt LaTeX-fill-break-before-code-comments
1451 Code comments are comments preceded by some other text in the same line.
1452 When a paragraph containing such a comment is to be filled, the comment
1453 start will be seen as a border after which no line breaks will be
1454 inserted in the same line. If the option
1455 @code{LaTeX-fill-break-before-code-comments} is enabled (which is the
1456 default) and the comment does not fit into the line, a line break will
1457 be inserted before the last non-comment word to minimize the chance that
1458 the line becomes overfull.
1462 @chapter Controlling Screen Display
1464 It is often desirable to get visual help of what markup code in a text
1465 actually does whithout having to decipher it explicitely. For this
1466 purpose Emacs and @AUCTeX{} provide font locking (also known as syntax
1467 highlighting) which visually sets off markup code like macros or
1468 environments by using different colors or fonts. For example text to be
1469 typeset in italics can be displayed with an italic font in the editor as
1470 well, or labels and references get their own distinct color.
1472 While font locking helps you grasp the purpose of markup code and
1473 separate markup from content, the markup code can still be distracting.
1474 @AUCTeX{} lets you hide those parts and show them again at request with
1475 its built-in support for hiding macros and environments which we call
1478 Besides folding of macros and environments, @AUCTeX{} provides support
1479 for Emacs' outline mode which lets you narrow the buffer content to
1480 certain sections of your text by hiding the parts not belonging to these
1484 * Font Locking:: Font Locking
1485 * Folding:: Folding Macros and Environments
1486 * Outline:: Outlining the Document
1490 @section Font Locking
1491 @cindex Font Locking
1492 @cindex Syntax Highlighting
1495 Font locking is supposed to improve readability of the source code by
1496 highlighting certain keywords with different colors or fonts. It
1497 thereby lets you recognize the function of markup code to a certain
1498 extent without having to read the markup command. For general
1499 information on controlling font locking with Emacs' Font Lock mode, see
1500 @ref{Font Lock, , Font Lock Mode, emacs, GNU Emacs Manual}.
1502 @defopt TeX-install-font-lock
1503 Once font locking is enabled globally or for the major modes provided by
1504 @AUCTeX{}, the font locking patterns and functionality of @fontlatex{}
1505 are activated by default. You can switch to a different font locking
1506 scheme or disable font locking in @AUCTeX{} by customizing the variable
1507 @code{TeX-install-font-lock}.
1509 Besides @fontlatex{} @AUCTeX{} ships with a scheme which is derived
1510 from Emacs' default @LaTeX{} mode and activated by choosing
1511 @code{tex-font-setup}. Be aware that this scheme is not coupled with
1512 @AUCTeX{}'s style system and not the focus of development. Therefore
1513 and due to @fontlatex{} being much more feature-rich the following
1514 explanations will only cover @fontlatex{}.
1516 In case you want to hook in your own fontification scheme, you can
1517 choose @code{other} and insert the name of the function which sets up
1518 your font locking patterns. If you want to disable fontification in
1519 @AUCTeX{} completely, choose @code{ignore}.
1522 @fontlatex{} provides many options for customization which are
1523 accessible with @kbd{M-x customize-group RET font-latex RET}. For this
1524 description the various options are explained in conceptional groups.
1527 * Fontification of macros:: Fontification of macros
1528 * Fontification of quotes:: Fontification of quotes
1529 * Fontification of math:: Fontification of math constructs
1530 * Verbatim content:: Verbatim macros and environments
1531 * Faces:: Faces used by font-latex
1532 * Known problems:: Known fontification problems
1535 @node Fontification of macros
1536 @subsection Fontification of macros
1538 Highlighting of macros can be customized by adapting keyword lists which
1539 can be found in the customization group @code{font-latex-keywords}.
1541 Three types of macros can be handled differently with respect to
1546 Commands of the form @samp{\foo[bar]@{baz@}} which consist of the macro
1547 itself, optional arguments in square brackets and mandatory arguments in
1548 curly braces. For the command itself the face
1549 @code{font-lock-keyword-face} will be used and for the optional
1550 arguments the face @code{font-lock-variable-name-face}. The face
1551 applied to the mandatory argument depends on the macro class represented
1552 by the respective built-in variables.
1554 Declaration macros of the form @samp{@{\foo text@}} which consist of the
1555 macro which may be enclosed in a @TeX{} group together with text to be
1556 affected by the macro. In case a @TeX{} group is present, the macro
1557 will get the face @code{font-lock-keyword-face} and the text will get
1558 the face configured for the respective macro class. If no @TeX{} group
1559 is present, the latter face will be applied to the macro itself.
1561 Simple macros of the form @samp{\foo} which do not have any arguments or
1562 groupings. The respective face will be applied to the macro itself.
1565 Customization variables for @samp{\foo[bar]@{baz@}} type macros allow
1566 both the macro name and the sequence of arguments to be specified. The
1567 latter is done with a string which can contain the characters
1570 indicating the existence of a starred variant for the macro,
1572 for optional arguments in brackets,
1574 for mandatory arguments in braces,
1576 for mandatory arguments consisting of a single macro and
1578 as a prefix indicating that two alternatives are following.
1580 For example the specifier for @samp{\documentclass} would be @samp{[@{}
1581 because the macro has one optional followed by one mandatory argument.
1582 The specifier for @samp{\newcommand} would be @samp{*|@{\[[@{} because
1583 there is a starred variant, the mandatory argument following the macro
1584 name can be a macro or a @TeX{} group which can be followed by two
1585 optional arguments and the last token is a mandatory argument in braces.
1587 Customization variables for the @samp{@{\foo text@}} and @samp{\foo}
1588 types are simple lists of strings where each entry is a macro name
1589 (without the leading backslash).
1591 @subheading General macro classes
1593 @fontlatex{} provides keyword lists for different macro classes which
1594 are described in the following table:
1596 @vindex font-latex-match-function-keywords
1597 @vindex font-latex-match-reference-keywords
1598 @vindex font-latex-match-textual-keywords
1599 @vindex font-latex-match-variable-keywords
1600 @vindex font-latex-match-warning-keywords
1602 @item font-latex-match-function-keywords
1603 Keywords for macros defining or related to functions, like
1604 @samp{\newcommand}.@*
1605 Type: @samp{\macro[...]@{...@}}@*
1606 Face: @code{font-lock-function-name-face}
1608 @item font-latex-match-reference-keywords
1609 Keywords for macros defining or related to references, like
1611 Type: @samp{\macro[...]@{...@}}@*
1612 Face: @code{font-lock-constant-face}
1614 @item font-latex-match-textual-keywords
1615 Keywords for macros specifying textual content, like @samp{\caption}.@*
1616 Type: @samp{\macro[...]@{...@}}@*
1617 Face: @code{font-lock-type-face}
1619 @item font-latex-match-variable-keywords
1620 Keywords for macros defining or related to variables, like
1621 @samp{\setlength}.@*
1622 Type: @samp{\macro[...]@{...@}}@*
1623 Face: @code{font-lock-variable-name-face}
1625 @item font-latex-match-warning-keywords
1626 Keywords for important macros, e.g. affecting line or page break, like
1627 @samp{\clearpage}.@*
1628 Type: @samp{\macro}@*
1629 Face: @code{font-latex-warning-face}
1632 @subheading Sectioning commands
1633 @cindex Sectioning commands, fontification of
1635 Sectioning commands are macros like @samp{\chapter} or @samp{\section}.
1636 For these commands there are two fontification schemes which may be
1637 selected by customizing the variable @code{font-latex-fontify-sectioning}.
1639 @defopt font-latex-fontify-sectioning
1640 @c Is @vindex correct?
1641 @vindex font-latex-sectioning-0-face
1642 @vindex font-latex-sectioning-1-face
1643 @vindex font-latex-sectioning-2-face
1644 @vindex font-latex-sectioning-3-face
1645 @vindex font-latex-sectioning-4-face
1646 @vindex font-latex-sectioning-5-face
1647 Per default sectioning commands will be shown in a larger, proportional
1648 font, which corresponds to a number for this variable. The font size
1649 varies with the sectioning level, e.g. @samp{\part}
1650 (@code{font-latex-sectioning-0-face}) has a larger font than
1651 @samp{\paragraph} (@code{font-latex-sectioning-5-face}). Typically,
1652 values from 1.05 to 1.3 for @code{font-latex-fontify-sectioning} give
1653 best results, depending on your font setup. If you rather like to use
1654 the base font and a different color, set the variable to the symbol
1655 @samp{color}. In this case the face @code{font-lock-type-face} will be
1656 used to fontify the argument of the sectioning commands.
1659 @vindex font-latex-match-sectioning-0-keywords
1660 @vindex font-latex-match-sectioning-1-keywords
1661 @vindex font-latex-match-sectioning-2-keywords
1662 @vindex font-latex-match-sectioning-3-keywords
1663 @vindex font-latex-match-sectioning-4-keywords
1664 @vindex font-latex-match-sectioning-5-keywords
1665 You can make @fontlatex{} aware of your own sectioning commands be
1666 adding them to the keyword lists:
1667 @code{font-latex-match-sectioning-0-keywords}
1668 (@code{font-latex-sectioning-0-face}) @dots{}
1669 @code{font-latex-match-sectioning-5-keywords}
1670 (@code{font-latex-sectioning-5-face}).
1672 @vindex font-latex-slide-title-face
1673 @vindex font-latex-match-slide-title-keywords
1674 Related to sectioning there is special support for slide titles which
1675 may be fontified with the face @code{font-latex-slide-title-face}. You
1676 can add macros which should appear in this face by customizing the
1677 variable @code{font-latex-match-slide-title-keywords}.
1679 @subheading Commands for changing fonts
1681 @LaTeX{} provides various macros for changing fonts or font attributes.
1682 For example, you can select an italic font with @samp{\textit@{...@}} or
1683 bold with @samp{\textbf@{...@}}. An alternative way to specify these
1684 fonts is to use special macros in @TeX{} groups, like @samp{@{\itshape
1685 ...@}} for italics and @samp{@{\bfseries ...@}} for bold. As mentioned
1686 above, we call the former variants commands and the latter
1689 Besides the macros for changing fonts provided by @LaTeX{} there is an
1690 infinite number of other macros---either defined by yourself for logical
1691 markup or defined by macro packages---which affect the font in the
1692 typeset text. While @LaTeX{}'s built-in macros and macros of packages
1693 known by @AUCTeX{} are already handled by @fontlatex{}, different
1694 keyword lists per type style and macro type are provided for entering
1695 your own macros which are listed in the table below.
1697 @vindex font-latex-match-bold-command-keywords
1698 @vindex font-latex-match-italic-command-keywords
1699 @vindex font-latex-match-math-command-keywords
1700 @vindex font-latex-match-type-command-keywords
1701 @vindex font-latex-match-bold-declaration-keywords
1702 @vindex font-latex-match-italic-declaration-keywords
1703 @vindex font-latex-match-type-declaration-keywords
1705 @item font-latex-match-bold-command-keywords
1706 Keywords for commands specifying a bold type style.@*
1707 Face: @code{font-latex-bold-face}
1708 @item font-latex-match-italic-command-keywords
1709 Keywords for commands specifying an italic font.@*
1710 Face: @code{font-latex-italic-face}
1711 @item font-latex-match-math-command-keywords
1712 Keywords for commands specifying a math font.@*
1713 Face: @code{font-latex-math-face}
1714 @item font-latex-match-type-command-keywords
1715 Keywords for commands specifying a typewriter font.@*
1716 Face: @code{font-lock-type-face}
1717 @item font-latex-match-bold-declaration-keywords
1718 Keywords for declarations specifying a bold type style.@*
1719 Face: @code{font-latex-bold-face}
1720 @item font-latex-match-italic-declaration-keywords
1721 Keywords for declarations specifying an italic font.@*
1722 Face: @code{font-latex-italic-face}
1723 @item font-latex-match-type-declaration-keywords
1724 Keywords for declarations specifying a typewriter font.@*
1725 Face: @code{font-latex-type-face}
1728 @subheading Deactivating defaults of built-in keyword classes
1730 @vindex font-latex-deactivated-keyword-classes
1731 @fontlatex{} ships with predefined lists of keywords for the classes
1732 described above. You can disable these defaults per class by
1733 customizing the variable @code{font-latex-deactivated-keyword-classes}.
1734 This is a list of strings for keyword classes to be deactivated. Valid
1735 entries are "warning", "variable", "reference", "function" ,
1736 "sectioning-0", "sectioning-1", "sectioning-2", "sectioning-3",
1737 "sectioning-4", "sectioning-5", "textual", "bold-command",
1738 "italic-command", "math-command", "type-command", "bold-declaration",
1739 "italic-declaration", "type-declaration".
1741 You can also get rid of certain keywords only. For example if you want
1742 to remove highlighting of footnotes as references you can put the
1743 following stanza into your init file:
1746 (eval-after-load "font-latex"
1748 font-latex-match-reference-keywords-local
1749 (remove "footnote" font-latex-match-reference-keywords-local)))
1752 But note that this means fiddling with @fontlatex{}'s internals and is
1753 not guaranteed to work in future versions of @fontlatex{}.
1755 @subheading User-defined keyword classes
1757 In case the customization options explained above do not suffice for
1758 your needs, you can specify your own keyword classes by customizing the
1759 variable @code{font-latex-user-keyword-classes}.
1761 @defopt font-latex-user-keyword-classes
1762 Every keyword class consists of four parts, a name, a list of keywords,
1763 a face and a specifier for the type of macros to be highlighted.
1765 When adding new entries, you have to use unique values for the class
1766 names, i.e. they must not clash with names of the built-in keyword
1767 classes or other names given by you. Additionally the names must not
1770 The list of keywords defines which commands and declarations should be
1771 covered by the keyword class. A keyword can either be a simple command
1772 name omitting the leading backslash or a list consisting of the command
1773 name and a string specifying the sequence of arguments for the command.
1775 The face argument can either be an existing face or font specifications
1776 made by you. (The latter option is not available on XEmacs.)
1778 There are three alternatives for the type of keywords---``Command with
1779 arguments'', ``Declaration inside @TeX{} group'' and ``Command without
1780 arguments''---which correspond with the macro types explained above.
1783 @node Fontification of quotes
1784 @subsection Fontification of quotes
1785 @cindex Quotes, fontification of
1787 Text in quotation marks is displayed with the face
1788 @code{font-latex-string-face}. Besides the various forms of opening and
1789 closing double and single quotation marks, so-called guillemets (<<, >>)
1790 can be used for quoting. Because there are two styles of using
1791 them---French style: << text >>; German style: >>text<<---you can
1792 customize the variable @code{font-latex-quotes} to tell @fontlatex{}
1793 which type you are using if the correct value cannot be derived from
1794 document properties.
1796 @defopt font-latex-quotes
1797 The default value of @code{font-latex-quotes} is @samp{auto} which means
1798 that @fontlatex{} will try to derive the correct type of quotation mark
1799 matching from document properties like the language option supplied to
1800 the babel @LaTeX{} package.
1802 If the automatic detection fails for you and you mostly use one specific
1803 style you can set it to a specific language-dependent value as well.
1804 Set the value to @samp{german} if you are using >>German quotes<< and to
1805 @samp{french} if you are using << French quotes >>. @fontlatex{} will
1806 recognize the different ways these quotes can be given in your source
1807 code, i.e. (@samp{"<}, @samp{">}), (@samp{<<}, @samp{>>}) and the
1808 respective 8-bit variants.
1810 If you set @code{font-latex-quotes} to nil, quoted content will not be
1815 @node Fontification of math
1816 @subsection Fontification of mathematical constructs
1817 @cindex Math, fontification of
1818 @cindex Subscript, fontification of
1819 @cindex Superscript, fontification of
1821 @vindex font-latex-match-math-command-keywords
1822 @vindex font-latex-math-environments
1823 In @LaTeX{} mathematics can be indicated by a variety of different
1824 methods: toggles (like dollar signs), macros and environments. Math
1825 constructs known by @fontlatex{} are displayed with the face
1826 @code{font-latex-math-face}. Support for dollar signs and shorthands
1827 like @samp{\(...\)} or @samp{\[...\]} is built-in and not customizable.
1828 Support for other math macros and environments can be adapted by
1829 customizing the variables @code{font-latex-match-math-command-keywords}
1830 and @code{font-latex-math-environments} respectively.
1832 In order to make math constructs more readable, @fontlatex{} displays
1833 subscript and superscript parts in a smaller font and raised or lowered
1834 respectively. This fontification feature can be controlled with the
1835 variables @code{font-latex-fontify-script} and
1836 @code{font-latex-script-display}.
1838 @defopt font-latex-fontify-script
1839 If non-nil, fontify subscript and superscript strings.
1841 Note that this feature is not available on XEmacs, for which it is
1842 disabled per default. In GNU Emacs raising and lowering is not enabled
1843 for versions 21.3 and before due to it working not properly.
1846 @defopt font-latex-script-display
1847 Display specification for subscript and superscript content. The car is
1848 used for subscript, the cdr is used for superscript. The feature is
1849 implemented using so-called display properties. For information on what
1850 exactly to specify for the values, see @ref{Other Display Specs, , Other
1851 Display Specifications, elisp, GNU Emacs Lisp Reference Manual}.
1854 @node Verbatim content
1855 @subsection Verbatim macros and environments
1856 @cindex Verbatim, fontification of
1858 Usually it is not desirable to have content to be typeset verbatim
1859 highlighted according to @LaTeX{} syntax. Therefore this content will
1860 be fontified uniformly with the face @code{font-latex-verbatim-face}.
1862 @vindex LaTeX-verbatim-macros-with-delims
1863 @vindex LaTeX-verbatim-macros-with-braces
1864 @vindex LaTeX-verbatim-environments
1865 @fontlatex{} differentiates three different types of verbatim
1866 constructs for fontification. Macros with special characters like | as
1867 delimiters, macros with braces, and environments. Which macros and
1868 environments are recognized is controlled by the variables
1869 @code{LaTeX-verbatim-macros-with-delims},
1870 @code{LaTeX-verbatim-macros-with-braces}, and
1871 @code{LaTeX-verbatim-environments} respectively.
1874 @subsection Faces used by @fontlatex{}
1877 In case you want to change the colors and fonts used by @fontlatex{}
1878 please refer to the faces mentioned in the explanations above and use
1879 @kbd{M-x customize-face RET <face> RET}. All faces defined by
1880 @fontlatex{} are accessible through a customization group by typing
1881 @kbd{M-x customize-group RET font-latex-highlighting-faces RET}.
1883 @node Known problems
1884 @subsection Known fontification problems
1885 @cindex Dollar signs, color bleed with
1886 @cindex Math, fontification problems with
1888 In certain cases the fontification machinery fails to interpret buffer
1889 contents correctly. This can lead to color bleed, i.e. large parts of a
1890 buffer get fontified with an inappropriate face. A typical situation
1891 for this to happen is the use of a dollar sign (@samp{$}) in a verbatim
1892 macro or environment. If @fontlatex{} is not aware of the verbatim
1893 construct, it assumes the dollar sign to be a toggle for mathematics and
1894 fontifies the following buffer content with the respective face until it
1895 finds a closing dollar sign or till the end of the buffer.
1897 As a remedy you can make the verbatim construct known to @fontlatex{},
1898 @pxref{Verbatim content}. If this is not possible, you can insert a
1899 commented dollar sign (@samp{%$}) at the next suitable end of line as a
1901 @c As a last resort one can set `font-lock-keywords-only', but we should
1902 @c probably not advise users to do this.
1906 @section Folding Macros and Environments
1913 A popular complaint about markup languages like @TeX{} and @LaTeX{} is
1914 that there is too much clutter in the source text and that one cannot
1915 focus well on the content. There are macros where you are only
1916 interested in the content they are enclosing, like font specifiers where
1917 the content might already be fontified in a special way by font locking.
1918 Or macros the content of which you only want to see when actually
1919 editing it, like footnotes or citations. Similarly you might find
1920 certain environments or comments distracting when trying to concentrate
1921 on the body of your document.
1923 With @AUCTeX{}'s folding functionality you can collapse those items and
1924 replace them by a fixed string, the content of one of their arguments,
1925 or a mixture of both. If you want to make the original text visible
1926 again in order to view or edit it, move point sideways onto the
1927 placeholder (also called display string) or left-click with the mouse
1928 pointer on it. (The latter is currently only supported on Emacs.) The
1929 macro or environment will unfold automatically, stay open as long as
1930 point is inside of it and collapse again once you move point out of it.
1931 (Note that folding of environments currently does not work in every
1934 In order to use this feature, you have to activate @code{TeX-fold-mode}
1935 which will activate the auto-reveal feature and the necessary commands
1936 to hide and show macros and environments. You can activate the mode in
1937 a certain buffer by typing the command @kbd{M-x TeX-fold-mode RET} or
1938 using the keyboard shortcut @kbd{C-c C-o C-f}. If you want to use it
1939 every time you edit a @LaTeX{} document, add it to a hook:
1940 @findex TeX-fold-mode
1944 (add-hook 'LaTeX-mode-hook (lambda ()
1948 If it should be activated in all @AUCTeX{} modes, use
1949 @code{TeX-mode-hook} instead of @code{LaTeX-mode-hook}.
1951 Once the mode is active there are several commands available to hide
1952 and show macros, environments and comments:
1954 @deffn Command TeX-fold-buffer
1956 (@kbd{C-c C-o C-b}) Hide all foldable items in the current buffer
1957 according to the setting of @code{TeX-fold-type-list}.
1959 If you want to have this done automatically every time you open a file,
1960 add it to a hook and make sure the function is called after font locking
1961 is set up for the buffer. The following code should accomplish this:
1964 (add-hook 'find-file-hook 'TeX-fold-buffer t)
1967 The command can be used any time to refresh the whole buffer and fold
1968 any new macros and environments which were inserted after the last
1969 invocation of the command.
1972 @defopt TeX-fold-type-list
1973 List of symbols determining the item classes to consider for folding.
1974 This can be macros, environments and comments. Per default only macros
1975 and environments are folded.
1978 @defopt TeX-fold-force-fontify
1979 In order for all folded content to get the right faces, the whole buffer
1980 has to be fontified before folding is carried out.
1981 @code{TeX-fold-buffer} therefore will force fontification of unfontified
1982 regions. As this will prolong the time folding takes, you can prevent
1983 forced fontification by customizing the variable
1984 @code{TeX-fold-force-fontify}.
1987 @defopt TeX-fold-preserve-comments
1988 By default items found in comments will be folded. If your comments
1989 often contain unfinished code this might lead to problems. Give this
1990 variable a non-nil value and foldable items in your comments will be
1994 @deffn Command TeX-fold-region
1996 (@kbd{C-c C-o C-r}) Hide all configured macros in the marked region.
1999 @deffn Command TeX-fold-paragraph
2001 (@kbd{C-c C-o C-p}) Hide all configured macros in the paragraph
2005 @deffn Command TeX-fold-macro
2007 (@kbd{C-c C-o C-m}) Hide the macro on which point currently is located.
2008 If the name of the macro is found in @code{TeX-fold-macro-spec-list},
2009 the respective display string will be shown instead. If it is not
2010 found, the name of the macro in sqare brackets or the default string for
2011 unspecified macros (@code{TeX-fold-unspec-macro-display-string}) will be
2012 shown, depending on the value of the variable
2013 @code{TeX-fold-unspec-use-name}.
2016 @deffn Command TeX-fold-env
2018 (@kbd{C-c C-o C-e}) Hide the environment on which point currently is
2019 located. The behavior regarding the display string is analogous to
2020 @code{TeX-fold-macro} and determined by the variables
2021 @code{TeX-fold-env-spec-list} and
2022 @code{TeX-fold-unspec-env-display-string} respectively.
2025 @deffn Command TeX-fold-math
2026 Hide the math macro on which point currently is located. If the name of
2027 the macro is found in @code{TeX-fold-math-spec-list}, the respective
2028 display string will be shown instead. If it is not found, the name of
2029 the macro in sqare brackets or the default string for unspecified macros
2030 (@code{TeX-fold-unspec-macro-display-string}) will be shown, depending
2031 on the value of the variable @code{TeX-fold-unspec-use-name}.
2034 @deffn Command TeX-fold-comment
2036 (@kbd{C-c C-o C-c}) Hide the comment point is located on.
2039 @deffn Command TeX-fold-clearout-buffer
2041 (@kbd{C-c C-o b}) Permanently unfold all macros and environments in the
2045 @deffn Command TeX-fold-clearout-region
2047 (@kbd{C-c C-o r}) Permanently unfold all macros and environments in the
2051 @deffn Command TeX-fold-clearout-paragraph
2053 (@kbd{C-c C-o p}) Permanently unfold all macros and environments in the
2054 paragraph containing point.
2057 @deffn Command TeX-fold-clearout-item
2059 (@kbd{C-c C-o i}) Permanently show the macro or environment on which
2060 point currently is located. In contrast to temporarily opening the
2061 macro when point is moved sideways onto it, the macro will be
2062 permanently unfolded and will not collapse again once point is leaving
2066 @deffn Command TeX-fold-dwim
2068 (@kbd{C-c C-o C-o}) Hide or show items according to the current context.
2069 If there is folded content, unfold it. If there is a marked region,
2070 fold all configured content in this region. If there is no folded
2071 content but a macro or environment, fold it.
2074 @vindex TeX-fold-command-prefix
2075 In case you want to use a different prefix than @kbd{C-c C-o} for these
2076 commands you can customize the variable @code{TeX-fold-command-prefix}.
2077 (Note that this will not change the key binding for activating the
2080 The commands above will only take macros or environments into
2081 consideration which are specified in the variables
2082 @code{TeX-fold-macro-spec-list} or @code{TeX-fold-env-spec-list}
2085 @defopt TeX-fold-macro-spec-list
2086 List of replacement specifiers and macros to fold. The specifier can be
2087 a string, an integer or a function symbol.
2089 If you specify a string, it will be used as a display replacement for
2090 the whole macro. Numbers in braces, brackets, parens or angle brackets
2091 will be replaced by the respective macro argument. For example
2092 @samp{@{1@}} will be replaced by the first mandatory argument of the
2093 macro. One can also define alternatives within the specifier which are
2094 used if an argument is not found. Alternatives are separated by
2095 @samp{||}. They are most useful with optional arguments. As an
2096 example, the default specifier for @samp{\item} is @samp{[1]:||*} which
2097 means that if there is an optional argument, its value is shown followed
2098 by a colon. If there is no optional argument, only an asterisk is used
2099 as the display string.
2101 If you specify a number as the first element, the content of the
2102 respective mandatory argument of a @LaTeX{} macro will be used as the
2105 If the first element is a function symbol, the function will be called
2106 with all mandatory arguments of the macro and the result of the function
2107 call will be used as a replacement for the macro.
2109 The placeholder is made by copying the text from the buffer together with
2110 its properties, i.e. its face as well. If fontification has not
2111 happened when this is done (e.g. because of lazy font locking) the
2112 intended fontification will not show up. As a workaround you can leave
2113 Emacs idle a few seconds and wait for stealth font locking to finish
2114 before you fold the buffer. Or you just re-fold the buffer with
2115 @code{TeX-fold-buffer} when you notice a wrong fontification.
2118 @defopt TeX-fold-env-spec-list
2119 List of display strings or argument numbers and environments to fold.
2120 Argument numbers refer to the @samp{\begin} statement. That means if
2121 you have e.g. @samp{\begin@{tabularx@}@{\linewidth@}@{XXX@} ...
2122 \end@{tabularx@}} and specify 3 as the argument number, the resulting
2123 display string will be ``XXX''.
2126 @defopt TeX-fold-math-spec-list
2127 List of display strings and math macros to fold.
2130 @vindex LaTeX-fold-macro-spec-list
2131 @vindex LaTeX-fold-env-spec-list
2132 @vindex LaTeX-fold-math-spec-list
2133 The variables @code{TeX-fold-macro-spec-list},
2134 @code{TeX-fold-env-spec-list}, and @code{TeX-fold-math-spec-list} apply
2135 to any @AUCTeX{} mode. If you want to make settings which are only
2136 applied to @LaTeX{} mode, you can use the mode-specific variables
2137 @code{LaTeX-fold-macro-spec-list}, @code{LaTeX-fold-env-spec-list}, and
2138 @code{LaTeX-fold-math-spec-list}
2140 @defopt TeX-fold-unspec-macro-display-string
2141 Default display string for macros which are not specified in
2142 @code{TeX-fold-macro-spec-list}.
2145 @defopt TeX-fold-unspec-env-display-string
2146 Default display string for environments which are not specified in
2147 @code{TeX-fold-env-spec-list}.
2150 @defopt TeX-fold-unspec-use-name
2151 If non-nil the name of the macro or environment surrounded by square
2152 brackets is used as display string, otherwise the defaults specified in
2153 @code{TeX-fold-unspec-macro-display-string} or
2154 @code{TeX-fold-unspec-env-display-string} respectively.
2157 When you hover with the mouse pointer over folded content, its original
2158 text will be shown in a tooltip or the echo area depending on Tooltip
2159 mode being activate. In order to avoid exorbitantly big tooltips and to
2160 cater for the limited space in the echo area the content will be cropped
2161 after a certain amount of characters defined by the variable
2162 @code{TeX-fold-help-echo-max-length}.
2164 @defopt TeX-fold-help-echo-max-length
2165 Maximum length of original text displayed in a tooltip or the echo area
2166 for folded content. Set it to zero in order to disable this feature.
2171 @section Outlining the Document
2178 @AUCTeX{} supports the standard outline minor mode using
2179 @LaTeX{}/@ConTeXt{} sectioning commands as header lines. @xref{Outline
2180 Mode, , Outline Mode, emacs, GNU Emacs Manual}.
2182 You can add your own headings by setting the variable
2183 @code{TeX-outline-extra}.
2185 @defvar TeX-outline-extra
2186 List of extra @TeX{} outline levels.
2188 Each element is a list with two entries. The first entry is the regular
2189 expression matching a header, and the second is the level of the header.
2190 A @samp{^} is automatically prepended to the regular expressions in the
2191 list, so they must match text at the beginning of the line.
2193 See @code{LaTeX-section-list} or @code{ConTeXt-INTERFACE-section-list}
2194 for existing header levels.
2197 The following example add @samp{\item} and @samp{\bibliography} headers,
2198 with @samp{\bibliography} at the same outline level as @samp{\section},
2199 and @samp{\item} being below @samp{\subparagraph}.
2202 (setq TeX-outline-extra
2203 '(("[ \t]*\\\\\\(bib\\)?item\\b" 7)
2204 ("\\\\bibliography\\b" 2)))
2207 You may want to check out the unbundled @file{out-xtra} package for even
2208 better outline support. It is available from your favorite emacs lisp
2212 @chapter Starting Processors, Viewers and Other Programs
2214 The most powerful features of @AUCTeX{} may be those allowing you to run
2215 @TeX{}, @LaTeX{}, @ConTeXt{} and other external commands like Bib@TeX{}
2216 and @code{makeindex} from within Emacs, viewing and printing the
2217 results, and moreover allowing you to @emph{debug} your documents.
2219 @cindex tool bar, toolbar
2220 @vindex LaTeX-enable-toolbar
2221 @vindex plain-TeX-enable-toolbar
2222 @AUCTeX{} comes with a special tool bar for @TeX{} and @LaTeX{} which
2223 provides buttons for the most important commands. You can enable or
2224 disable it by customizing the options @code{plain-TeX-enable-toolbar}
2225 and @code{LaTeX-enable-toolbar} in the @code{TeX-tool-bar} customization
2229 * Commands:: Invoking external commands.
2230 * Viewing:: Invoking external viewers.
2231 * Debugging:: Debugging @TeX{} and @LaTeX{} output.
2232 * Checking:: Checking the document.
2233 * Control:: Controlling the processes.
2234 * Cleaning:: Cleaning intermediate and output files.
2235 * Documentation:: Documentation about macros and packages.
2239 @section Executing Commands
2241 @cindex Running @LaTeX{}
2242 @cindex Running @TeX{}
2245 @cindex Running commands
2246 @cindex Default command
2249 @cindex Setting the header
2250 @cindex Setting the trailer
2253 @cindex Setting the default command
2255 @cindex External Commands
2257 @cindex Making an index
2258 @cindex Running @code{makeindex}
2259 @cindex @code{makeindex}
2261 @cindex Bibliography
2263 @cindex Running Bib@TeX{}
2264 @cindex Making a bibliography
2266 @cindex Writing to a printer
2268 Formatting the document with @TeX{}, @LaTeX{} or @ConTeXt{}, viewing
2269 with a previewer, printing the document, running Bib@TeX{}, making an
2270 index, or checking the document with @command{lacheck} or
2271 @command{chktex} all require running an external command.
2274 * Starting a Command:: Starting a Command on a Document or Region
2275 * Selecting a Command:: Selecting and Executing a Command
2276 * Processor Options:: Options for @TeX{} Processors
2279 @node Starting a Command
2280 @subsection Starting a Command on a Document or Region
2282 There are two ways to run an external command, you can either run it on
2283 the current document with @code{TeX-command-master}, or on the current
2284 region with @code{TeX-command-region}. A special case of running @TeX{}
2285 on a region is @code{TeX-command-buffer} which differs from
2286 @code{TeX-command-master} if the current buffer is not its own master
2289 @deffn Command TeX-command-master
2291 (@kbd{C-c C-c}) Query the user for a command, and run it on the master
2292 file associated with the current buffer. The name of the master file is
2293 controlled by the variable @code{TeX-master}. The available commands are
2294 controlled by the variable @code{TeX-command-list}.
2296 @vindex TeX-command-list
2299 @deffn Command TeX-command-region
2301 (@kbd{C-c C-r}) Query the user for a command, and run it on the contents
2302 of the selected region. The region contents are written into the region
2303 file, after extracting the header and trailer from the master file. If
2304 mark is inactive (which can happen with Transient Mark mode), use the
2305 old region. See also the command @code{TeX-pin-region} about how to fix
2308 The name of the region file is controlled by the variable
2309 @code{TeX-region}. The name of the master file is controlled by the
2310 variable @code{TeX-master}. The header is all text up to the line
2311 matching the regular expression @code{TeX-header-end}. The trailer is
2312 all text from the line matching the regular expression
2313 @code{TeX-trailer-start}. The available commands are controlled by the
2314 variable @code{TeX-command-list}.
2316 @vindex TeX-header-end
2317 @vindex TeX-trailer-start
2319 @vindex TeX-command-list
2322 @deffn Command TeX-command-buffer
2324 (@kbd{C-c C-b}) Query the user for a command, and apply it to the
2325 contents of the current buffer. The buffer contents are written into
2326 the region file, after extracting the header and trailer from the master
2327 file. The command is then actually run on the region file. See above
2332 The name of the file for temporarily storing the text when formatting
2336 @defopt TeX-header-end
2337 A regular expression matching the end of the header. By default, this
2338 is @samp{\begin@{document@}} in @LaTeX{} mode and @samp{%**end of
2339 header} in @TeX{} mode.
2342 @defopt TeX-trailer-start
2343 A regular expression matching the start of the trailer. By default,
2344 this is @samp{\end@{document@}} in @LaTeX{} mode and @samp{\bye} in
2348 If you want to change the values of @code{TeX-header-end} and
2349 @code{TeX-trailer-start} you can do this for all files by setting the
2350 variables in a mode hook or per file by specifying them as file
2351 variables (@pxref{File Variables,,,emacs,The Emacs Editor}).
2353 @deffn Command TeX-pin-region
2355 (@kbd{C-c C-t C-r}) If you don't have a mode like Transient Mark mode
2356 active, where marks get disabled automatically, the region would need to
2357 get properly set before each call to @code{TeX-command-region}. If you
2358 fix the current region with @kbd{C-c C-t C-r}, then it will get used for
2359 more commands even though mark and point may change. An explicitly
2360 activated mark, however, will always define a new region when calling
2361 @code{TeX-command-region}.
2364 @AUCTeX{} will allow one process for each document, plus one process
2365 for the region file to be active at the same time. Thus, if you are
2366 editing @var{n} different documents, you can have @var{n} plus one
2367 processes running at the same time. If the last process you started was
2368 on the region, the commands described in @ref{Debugging} and
2369 @ref{Control} will work on that process, otherwise they will work on the
2370 process associated with the current document.
2372 @node Selecting a Command
2373 @subsection Selecting and Executing a Command
2375 Once you started the command selection with @kbd{C-c C-c}, @kbd{C-c C-s}
2376 or @kbd{C-c C-b} you will be prompted for the type of command.
2377 @AUCTeX{} will try to guess which command is appropriate in the given
2378 situation and propose it as default. Usually this is a processor like
2379 @samp{TeX} or @samp{LaTeX} if the document was changed or a viewer if
2380 the document was just typeset. Other commands can be selected in the
2381 minibuffer with completion support by typing @key{TAB}.
2383 @vindex TeX-command-list
2384 @vindex TeX-expand-list
2385 The available commands are defined by the variable
2386 @code{TeX-command-list}. Per default it includes commands for
2387 typesetting the document (e.g. @samp{LaTeX}), for viewing the output
2388 (@samp{View}), for printing (@samp{Print}), for generating an index
2389 (@samp{Index}) or for spell checking (@samp{Spell}) to name but a few.
2390 You can also add your own commands by adding entries to
2391 @code{TeX-command-list}. Refer to its doc string for information about
2392 its syntax. You might also want to look at @code{TeX-expand-list} to
2393 learn about the expanders you can use in @code{TeX-command-list}.
2395 Note that the default of the variable occasionally changes. Therefore
2396 it is advisable to add to the list rather than overwriting it. You can
2397 do this with a call to @code{add-to-list} in your init file. For
2398 example, if you wanted to add a command for running a program called
2399 @samp{foo} on the master or region file, you could do this with the
2403 (eval-after-load "tex"
2404 '(add-to-list 'TeX-command-list
2405 '("Foo" "foo %s" TeX-run-command t t :help "Run foo") t))
2408 As mentioned before, @AUCTeX{} will try to guess what command you want
2409 to invoke. If you want to use another command than @samp{TeX},
2410 @samp{LaTeX} or whatever processor @AUCTeX{} thinks is appropriate for
2411 the current mode, set the variable @code{TeX-command-default}. You can
2412 do this for all files by setting it in a mode hook or per file by
2413 specifying it as a file variable (@pxref{File Variables,,,emacs,The
2416 @defopt TeX-command-default
2417 The default command to run in this buffer. Must be an entry in
2418 @code{TeX-command-list}.
2423 @vindex LaTeX-biblatex-use-Biber
2424 In case you use biblatex in a document, @AUCTeX{} switches from
2425 Bib@TeX{} to Biber for bibliography processing. In case you want to
2426 keep using Bib@TeX{}, set the variable @code{LaTeX-biblatex-use-Biber}
2429 After confirming a command to execute, @AUCTeX{} will try to save any
2430 buffers related to the document, and check if the document needs to be
2431 reformatted. If the variable @code{TeX-save-query} is non-nil,
2432 @AUCTeX{} will query before saving each file. By default @AUCTeX{} will
2433 check emacs buffers associated with files in the current directory, in
2434 one of the @code{TeX-macro-private} directories, and in the
2435 @code{TeX-macro-global} directories. You can change this by setting the
2436 variable @code{TeX-check-path}.
2438 @defopt TeX-check-path
2439 Directory path to search for dependencies.
2441 If nil, just check the current file.
2442 Used when checking if any files have changed.
2445 @node Processor Options
2446 @subsection Options for @TeX{} Processors
2448 There are some options you can customize affecting which processors are
2449 invoked or the way this is done and which output they produce as a
2450 result. These options control if @acronym{DVI} or @acronym{PDF} output
2451 should be produced, if @TeX{} should be started in interactive or
2452 nonstop mode, if source specials or a Sync@TeX{} file should be produced
2453 for making inverse and forward search possible or which @TeX{} engine
2454 should be used instead of regular @TeX{}, like PDF@TeX{}, Omega or
2457 @deffn Command TeX-PDF-mode
2459 @vindex TeX-PDF-mode
2462 This command toggles the @acronym{PDF} mode of @AUCTeX{}, a buffer-local
2463 minor mode. You can customize @code{TeX-PDF-mode} to give it a
2464 different default. The default is used when @AUCTeX{} does not have
2465 additional clue about what a document might want. This option usually
2466 results in calling either PDF@TeX{} or ordinary @TeX{}.
2469 @defopt TeX-DVI-via-PDFTeX
2470 If this is set, @acronym{DVI} will also be produced by calling
2471 PDF@TeX{}, setting @code{\pdfoutput=0}. This makes it possible to use
2472 PDF@TeX{} features like character protrusion even when producing
2473 @acronym{DVI} files. Contemporary @TeX{} distributions do this anyway,
2474 so that you need not enable the option within @AUCTeX{}.
2477 @deffn Command TeX-interactive-mode
2479 @vindex TeX-interactive-mode
2480 (@kbd{C-c C-t C-i}) This command toggles the interactive mode of
2481 @AUCTeX{}, a global minor mode. You can customize
2482 @code{TeX-interactive-mode} to give it a different default. In
2483 interactive mode, @TeX{} will pause with an error prompt when errors are
2484 encountered and wait for the user to type something.
2487 @cindex I/O correlation
2489 @cindex Source specials
2491 @deffn Command TeX-source-correlate-mode
2493 @vindex TeX-source-correlate-mode
2494 (@kbd{C-c C-t C-s}) Toggles support for forward and inverse search.
2495 Forward search refers to jumping to the place in the previewed document
2496 corresponding to where point is located in the document source and
2497 inverse search to the other way round. @xref{I/O Correlation}.
2499 You can permanently activate @code{TeX-source-correlate-mode} by
2500 customizing the variable @code{TeX-source-correlate-mode}. There is a
2501 bunch of customization options for the mode, use @kbd{M-x
2502 customize-group @key{RET} TeX-view @key{RET}} to find out more.
2504 @vindex TeX-source-correlate-method
2505 @AUCTeX{} is aware of three different means to do I/O correlation:
2506 source specials (only DVI output), the pdfsync @LaTeX{} package (only
2507 PDF output) and Sync@TeX{}. The choice between source specials and
2508 Sync@TeX{} can be controlled with the variable
2509 @code{TeX-source-correlate-method}.
2511 Should you use source specials it has to be stressed @emph{very}
2512 strongly however, that source specials can cause differences in page
2513 breaks and spacing, can seriously interfere with various packages and
2514 should thus @emph{never} be used for the final version of a document.
2515 In particular, fine-tuning the page breaks should be done with source
2516 specials switched off.
2519 @AUCTeX{} also allows you to easily select different @TeX{} engines for
2520 processing, either by using the entries in the @samp{TeXing Options}
2521 submenu below the @samp{Command} menu or by calling the function
2522 @code{TeX-engine-set}. These eventually set the variable
2523 @code{TeX-engine} which you can also modify directly.
2526 This variable allows you to choose which @TeX{} engine should be used
2527 for typesetting the document, i.e. the executables which will be used
2528 when you invoke the @samp{TeX} or @samp{LaTeX} commands. The value
2529 should be one of the symbols defined in @code{TeX-engine-alist-builtin}
2530 or @code{TeX-engine-alist}. The symbols @samp{default}, @samp{xetex},
2531 @samp{luatex} and @samp{omega} are available from the built-in list.
2534 Note that @code{TeX-engine} is buffer-local, so setting the variable
2535 directly or via the above mentioned menu or function will not take
2536 effect in other buffers. If you want to activate an engine for all
2537 @AUCTeX{} modes, set @code{TeX-engine} in your init file, e.g. by using
2538 @kbd{M-x customize-variable <RET>}. If you want to activate it for a
2539 certain @AUCTeX{} mode only, set the variable in the respective mode
2540 hook. If you want to activate it for certain files, set it through file
2541 variables (@pxref{File Variables,,,emacs,The Emacs Editor}).
2544 @vindex LaTeX-command
2545 @vindex TeX-Omega-command
2546 @vindex LaTeX-Omega-command
2547 @vindex ConTeXt-engine
2548 @vindex ConTeXt-Omega-engine
2549 @vindex TeX-engine-alist
2550 @vindex TeX-engine-alist-builtin
2551 Should you need to change the executable names related to the different
2552 engine settings, there are some variables you can tweak. Those are
2553 @code{TeX-command}, @code{LaTeX-command}, @code{TeX-Omega-command},
2554 @code{LaTeX-Omega-command}, @code{ConTeXt-engine} and
2555 @code{ConTeXt-Omega-engine}. The rest of the executables is defined
2556 directly in @code{TeX-engine-alist-builtin}. If you want to override an
2557 entry from that, add an entry to @code{TeX-engine-alist} that starts
2558 with the same symbol as that the entry in the built-in list and specify
2559 the executables you want to use instead. You can also add entries to
2560 @code{TeX-engine-alist} in order to add support for engines not covered
2563 @defopt TeX-engine-alist
2564 Alist of TeX engines and associated commands. Each entry is a list with
2565 a maximum of five elements. The first element is a symbol used to
2566 identify the engine. The second is a string describing the engine. The
2567 third is the command to be used for plain TeX. The fourth is the
2568 command to be used for LaTeX. The fifth is the command to be used for
2569 the @samp{--engine} parameter of ConTeXt's @samp{texexec} program. Each
2570 command can either be a variable or a string. An empty string or nil
2571 means there is no command available.
2574 You can customize @AUCTeX{} to show the processor output as it is
2577 @defopt TeX-show-compilation
2578 If non-nil, the output of @TeX{} compilation is shown in another window.
2582 @section Viewing the Formatted Output
2585 @cindex Starting a previewer
2587 @AUCTeX{} allows you to start external programs for previewing the
2588 formatted output of your document.
2591 * Starting Viewers:: Starting viewers
2592 * I/O Correlation:: Forward and inverse search
2595 @node Starting Viewers
2596 @subsection Starting Viewers
2598 Viewers are normally invoked by pressing @kbd{C-c C-c} once the document
2599 is formatted, which will propose the View command, or by activating the
2600 respective entry in the Command menu. Alternatively you can type
2601 @kbd{C-c C-v} which calls the function @code{TeX-view}.
2603 @deffn Command TeX-view
2605 (@kbd{C-c C-v}) Start a viewer without confirmation. The viewer is
2606 started either on a region or the master file, depending on the last
2607 command issued. This is especially useful for jumping to the location
2608 corresponding to point in the viewer when using
2609 @code{TeX-source-correlate-mode}.
2612 @AUCTeX{} will try to guess which type of viewer (@acronym{DVI},
2613 PostScript or @acronym{PDF}) has to be used and what options are to be
2614 passed over to it. This decision is based on the output files present
2615 in the working directory as well as the class and style options used in
2616 the document. For example, if there is a @acronym{DVI} file in your
2617 working directory, a @acronym{DVI} viewer will be invoked. In case of a
2618 @acronym{PDF} file it will be a @acronym{PDF} viewer. If you specified
2619 a special paper format like @samp{a5paper} or use the @samp{landscape}
2620 option, this will be passed to the viewer by the appropriate options.
2621 Especially some @acronym{DVI} viewers depend on this kind of information
2622 in order to display your document correctly. In case you are using
2623 @samp{pstricks} or @samp{psfrag} in your document, a @acronym{DVI}
2624 viewer cannot display the contents correctly and a PostScript viewer
2625 will be invoked instead.
2627 The association between the tests for the conditions mentioned above and
2628 the viewers is made in the variable @code{TeX-view-program-selection}.
2629 Therefore this variable is the starting point for customization if you
2630 want to use other viewers than the ones suggested by default.
2632 @defopt TeX-view-program-selection
2633 This is a list of predicates and viewers which is evaluated from front
2634 to back in order to find out which viewer to call under the given
2635 conditions. In the first element of each list item you can reference
2636 one or more predicates defined in @code{TeX-view-predicate-list} or
2637 @code{TeX-view-predicate-list-builtin}. In the second element you can
2638 reference a viewer defined in @code{TeX-view-program-list} or
2639 @code{TeX-view-program-list-builtin}. The viewer of the first item with
2640 a positively evaluated predicate is selected.
2643 So @code{TeX-view-program-selection} only contains references to the
2644 actual implementations of predicates and viewer commands respectively
2645 which can be found elsewhere. @AUCTeX{} comes with a set of
2646 preconfigured predicates and viewer commands which are stored in the
2647 variables @code{TeX-view-predicate-list-builtin} and
2648 @code{TeX-view-program-list-builtin} respectively. If you are not
2649 satisfied with those and want to overwrite one of them or add your own
2650 definitions, you can do so via the variables
2651 @code{TeX-view-predicate-list} and @code{TeX-view-program-list}.
2653 @defopt TeX-view-predicate-list
2654 This is a list of predicates for viewer selection and invocation. The
2655 first element of each list item is a symbol and the second element a
2656 Lisp form to be evaluated. The form should return nil if the predicate
2659 A built-in predicate from @code{TeX-view-predicate-list-builtin} can be
2660 overwritten by defining a new predicate with the same symbol.
2663 @defopt TeX-view-program-list
2664 This is a list of viewer specifications each consisting of a symbolic
2665 name and either a command line or a function to be invoked when the
2666 viewer is called. If a command line is used, parts of it can be
2667 conditionalized by prefixing them with predicates from
2668 @code{TeX-view-predicate-list} or
2669 @code{TeX-view-predicate-list-builtin}. (See the doc string for the
2670 exact format to use.) The command line can also contain placeholders as
2671 defined in @code{TeX-expand-list} which are expanded before the viewer
2674 A built-in viewer spec from @code{TeX-view-program-list-builtin} can be
2675 overwritten by defining a new viewer spec with the same name.
2678 Note that the viewer selection and invocation as described above will
2679 only work if certain default settings in @AUCTeX{} are intact. For one,
2680 the whole viewer selection machinery will only be triggered if the
2681 @samp{%V} expander in @code{TeX-expand-list} is unchanged. So if you
2682 have trouble with the viewer invocation you might check if there is an
2683 older customization of the variable in place. In addition, the use of a
2684 function in @code{TeX-view-program-list} only works if the View command
2685 in @code{TeX-command-list} makes use of the hook
2686 @code{TeX-run-discard-or-function}.
2688 Note also that the implementation described above replaces an older one
2689 which was less flexible. This old implementation works with the
2690 variables @code{TeX-output-view-style} and @code{TeX-view-style} which
2691 are used to associate file types and style options with viewers. If
2692 desired you can reactivate it by using the placeholder @samp{%vv} for
2693 the View command in @code{TeX-command-list}. Note however, that it is
2694 bound to be removed from @AUCTeX{} once the new implementation proved to
2695 be satisfactory. For the time being, find a short description of the
2696 mentioned customization options below.
2698 @defopt TeX-output-view-style
2699 List of output file extensions, style options and view options. Each
2700 item of the list consists of three elements. If the first element (a
2701 regular expression) matches the output file extension, and the second
2702 element (a regular expression) matches the name of one of the style
2703 options, any occurrence of the string @code{%V} in a command in
2704 @code{TeX-command-list} will be replaced with the third element.
2707 @defopt TeX-view-style
2708 List of style options and view options. This is the predecessor of
2709 @code{TeX-output-view-style} which does not provide the possibility to
2710 specify output file extensions. It is used as a fallback in case none
2711 of the alternatives specified in @code{TeX-output-view-style} match. In
2712 case none of the entries in @code{TeX-view-style} match either, no
2713 suggestion for a viewer is made.
2716 @node I/O Correlation
2717 @subsection Forward and Inverse Search
2718 @cindex Inverse search
2719 @cindex Forward search
2720 @cindex I/O correlation
2721 @cindex Source specials
2725 Forward and inverse search refer to the correlation between the document
2726 source in the editor and the typeset document in the viewer. Forward
2727 search allows you to jump to the place in the previewed document
2728 corresponding to a certain line in the document source and inverse
2731 @findex TeX-source-correlate-mode
2732 @AUCTeX{} supports three methods for forward and inverse search: source
2733 specials (only DVI output), the pdfsync @LaTeX{} package (only PDF
2734 output) and Sync@TeX{} (any type of output). If you want to make use of
2735 forward and inverse searching with source specials or Sync@TeX{}, switch
2736 on @code{TeX-source-correlate-mode}. @xref{Processor Options}, on how
2737 to do that. The use of the pdfsync package is detected automatically if
2738 document parsing is enabled.
2741 Forward search happens automatically upon calling the viewer, e.g. by
2742 typing @kbd{C-c C-v} (@code{TeX-view}). This will open the viewer or
2743 bring it to front and display the output page corresponding to the
2744 position of point in the source file. @AUCTeX{} will automatically pass
2745 the necessary command line options to the viewer for this to happen.
2747 @vindex TeX-source-correlate-start-server
2748 Upon opening the viewer you will be asked if you want to start a server
2749 process (Gnuserv or Emacs server) which is necessary for inverse search.
2750 This happens only if there is no server running already. You can
2751 customize the variable @code{TeX-source-correlate-start-server} to
2752 inhibit the question and always or never start the server respectively.
2754 @defopt TeX-source-correlate-start-server
2755 If @code{TeX-source-correlate-mode} is active and a viewer is invoked,
2756 the default behavior is to ask if a server process should be started.
2757 Set this variable to @code{t} if the question should be inhibited and
2758 the server should always be started. Set it to @code{nil} if the server
2759 should never be started. Inverse search will not be available in the
2763 Inverse search, i.e. jumping to the part of your document source in
2764 Emacs corresponding to a certain position in the viewer, is triggered
2765 from the viewer, typically by a mouse click. Refer to the documentation
2766 of your viewer to find out how it has to be configured and what you have
2767 to do exactly. In xdvi you normally have to use @kbd{C-down-mouse-1}.
2770 @section Catching the errors
2773 @cindex Parsing errors
2774 @cindex Parsing TeX output
2776 @cindex Parsing @LaTeX{} errors
2777 @cindex Overfull boxes
2779 @cindex Underfull boxes
2781 Once you've formatted your document you may `debug' it, i.e. browse
2782 through the errors (La)@TeX{} reported.
2784 @deffn Command TeX-next-error
2786 (@kbd{C-c `}) Go to the next error reported by @TeX{}. The view will
2787 be split in two, with the cursor placed as close as possible to the
2788 error in the top view. In the bottom view, the error message will be
2789 displayed along with some explanatory text.
2792 Normally @AUCTeX{} will only report real errors, but you may as well
2793 ask it to report `bad boxes' and warnings as well.
2795 @deffn Command TeX-toggle-debug-bad-boxes
2797 (@kbd{C-c C-t C-b}) Toggle whether @AUCTeX{} should stop at bad boxes
2798 (i.e. overfull and underfull boxes) as well as normal errors.
2801 @deffn Command TeX-toggle-debug-warnings
2803 (@kbd{C-c C-t C-w}) Toggle whether @AUCTeX{} should stop at warnings as
2804 well as normal errors.
2807 As default, @AUCTeX{} will display a special help buffer containing the
2808 error reported by @TeX{} along with the documentation. There is however
2809 an `expert' option, which allows you to display the real @TeX{} output.
2811 @defopt TeX-display-help
2812 If t @AUCTeX{} will automatically display a help text whenever an error
2813 is encountered using @code{TeX-next-error} (@kbd{C-c `}). If nil a
2814 terse information about the error is displayed in the echo area. If
2815 @code{expert} @AUCTeX{} will display the output buffer with the raw
2820 @section Checking for problems
2822 @cindex @code{lacheck}
2823 @cindex @code{chktex}
2824 @cindex Finding errors
2825 @cindex Running @code{lacheck}
2826 @cindex Running @code{chktex}
2830 Running @TeX{} or @LaTeX{} will only find regular errors in the
2831 document, not examples of bad style. Furthermore, description of the
2832 errors may often be confusing. The utility @code{lacheck} can be used
2833 to find style errors, such as forgetting to escape the space after an
2834 abbreviation or using @samp{...} instead of @samp{\ldots} and many other
2835 problems like that. You start @code{lacheck} with @kbd{C-c C-c Check
2836 @key{RET}}. The result will be a list of errors in the
2837 @samp{*compilation*} buffer. You can go through the errors with
2838 @kbd{C-x `} (@code{next-error}, @pxref{Compilation,,,emacs,The Emacs
2839 Editor}), which will move point to the location of the next error.
2841 Another newer program which can be used to find errors is @code{chktex}.
2842 It is much more configurable than @code{lacheck}, but doesn't find all
2843 the problems @code{lacheck} does, at least in its default configuration.
2844 You must install the programs before using them, and for @code{chktex}
2845 you may also need modify @code{TeX-command-list} unless you use its
2846 @code{lacheck} compatibility wrapper. You can get @code{lacheck} from
2847 @file{<URL:ftp://ftp.ctan.org/tex-archive/support/lacheck/>} or
2848 alternatively @code{chktex} from
2849 @file{<URL:ftp://ftp.ctan.org/tex-archive/support/chktex/>}.
2852 @section Controlling the output
2853 @cindex Controlling the output
2855 @cindex Redisplay output
2857 @cindex Killing a process
2858 @cindex Finding the master file
2860 @cindex Stopping a process
2861 @cindex Current file
2862 @cindex Finding the current file
2864 A number of commands are available for controlling the output of an
2865 application running under @AUCTeX{}
2867 @deffn Command TeX-kill-job
2869 (@kbd{C-c C-k}) Kill currently running external application.
2870 This may be either of @TeX{}, @LaTeX{}, previewer, Bib@TeX{}, etc.
2873 @deffn Command TeX-recenter-output-buffer
2875 (@kbd{C-c C-l}) Recenter the output buffer so that the bottom line is
2879 @deffn Command TeX-home-buffer
2881 (@kbd{C-c ^}) Go to the `master' file in the document associated with
2882 the current buffer, or if already there, to the file where the current
2883 process was started.
2887 @section Cleaning intermediate and output files
2890 @deffn Command TeX-clean
2891 @vindex plain-TeX-clean-intermediate-suffixes
2892 @vindex plain-TeX-clean-output-suffixes
2893 @vindex LaTeX-clean-intermediate-suffixes
2894 @vindex LaTeX-clean-output-suffixes
2895 @vindex docTeX-clean-intermediate-suffixes
2896 @vindex docTeX-clean-output-suffixes
2897 @vindex Texinfo-clean-intermediate-suffixes
2898 @vindex Texinfo-clean-output-suffixes
2899 @vindex ConTeXt-clean-intermediate-suffixes
2900 @vindex ConTeXt-clean-output-suffixes
2901 Remove generated intermediate files. In case a prefix argument is
2902 given, remove output files as well.
2904 Canonical access to the function is provided by the @samp{Clean} and
2905 @samp{Clean All} entries in @code{TeX-command-list}, invokable with
2906 @kbd{C-c C-c} or the Command menu.
2908 The patterns governing which files to remove can be adapted separately
2909 for each @AUCTeX{} mode by means of the variables
2910 @code{plain-TeX-clean-intermediate-suffixes},
2911 @code{plain-TeX-clean-output-suffixes},
2912 @code{LaTeX-clean-intermediate-suffixes},
2913 @code{LaTeX-clean-output-suffixes},
2914 @code{docTeX-clean-intermediate-suffixes},
2915 @code{docTeX-clean-output-suffixes},
2916 @code{Texinfo-clean-intermediate-suffixes},
2917 @code{Texinfo-clean-output-suffixes},
2918 @code{ConTeXt-clean-intermediate-suffixes} and
2919 @code{ConTeXt-clean-output-suffixes}.
2922 @defopt TeX-clean-confirm
2923 Control if deletion of intermediate and output files has to be confirmed
2924 before it is actually done. If non-nil, ask before deleting files.
2928 @section Documentation about macros and packages
2929 @cindex Documentation
2931 @deffn Command TeX-doc
2933 (@kbd{C-c ?}) Get documentation about macros, packages or @TeX{} &
2934 Co. in general. The function will prompt for the name of a command or
2935 manual, providing a list of available keywords for completion. If point
2936 is on a command or word with available documentation, this will be
2937 suggested as default.
2939 In case no documentation could be found, a prompt for querying the
2940 @samp{texdoc} program is shown, should the latter be available.
2942 The command can be invoked by the key binding mentioned above as well as
2943 the @samp{Find Documentation...} entry in the mode menu.
2947 @chapter Customization and Extension
2950 * Modes and Hooks:: Modes and Hooks
2951 * Multifile:: Multifile Documents
2952 * Parsing Files:: Automatic Parsing of @TeX{} Files
2953 * Internationalization:: Language Support
2954 * Automatic:: Automatic Customization
2955 * Style Files:: Writing Your Own Style Support
2958 @node Modes and Hooks
2959 @section Modes and Hooks
2961 @AUCTeX{} supports a wide variety of derivatives and extensions of
2962 @TeX{}. Besides plain @TeX{} those are @LaTeX{}, AMS-@TeX{},
2963 @ConTeXt{}, Texinfo and doc@TeX{}. For each of them there is a separate
2964 major mode in @AUCTeX{} and each major mode runs @code{text-mode-hook},
2965 @code{TeX-mode-hook} as well as a hook special to the mode in this
2966 order. The following table provides an overview of the respective mode
2967 functions and hooks.
2969 @multitable {Plain @TeX{}} {@code{plain-TeX-mode}} {@code{plain-TeX-mode-hook}}
2970 @headitem Type @tab Mode function @tab Hook
2971 @item Plain @TeX{} @tab @code{plain-TeX-mode} @tab @code{plain-TeX-mode-hook}
2972 @item @LaTeX{} @tab @code{LaTeX-mode} @tab @code{LaTeX-mode-hook}
2973 @item AMS-@TeX{} @tab @code{ams-tex-mode} @tab @code{AmS-TeX-mode-hook}
2974 @item @ConTeXt{} @tab @code{ConTeXt-mode} @tab @code{ConTeXt-mode-hook}
2975 @item Texinfo @tab @code{Texinfo-mode} @tab @code{Texinfo-mode-hook}
2976 @item Doc@TeX{} @tab @code{docTeX-mode} @tab @code{docTeX-mode-hook}
2979 If you need to make a customization via a hook which is only relevant
2980 for one of the modes listed above, put it into the respective mode hook,
2981 if it is relevant for any @AUCTeX{} mode, add it to @code{TeX-mode-hook}
2982 and if it is relevant for all text modes, append it to
2983 @code{text-mode-hook}.
2986 @section Multifile Documents
2987 @cindex Multifile Documents
2989 @cindex Documents with multiple files
2990 @cindex Multiple Files
2998 You may wish to spread a document over many files (as you are likely to do if
2999 there are multiple authors, or if you have not yet discovered the power
3000 of the outline commands (@pxref{Outline})). This can be done by having a
3001 ``master'' file in which you include the various files with the @TeX{}
3002 macro @samp{\input} or the @LaTeX{} macro @samp{\include}. These
3003 files may also include other files themselves. However, to format the
3004 document you must run the commands on the top level master file.
3006 When you, for example, ask @AUCTeX{} to run a command on the master file,
3007 it has no way of knowing the name of the master file. By default,
3008 it will assume that the current file is the master file. If you insert
3009 the following in your @file{.emacs} file @AUCTeX{} will use a more
3013 (setq-default TeX-master nil) ; Query for master file.
3016 If @AUCTeX{} finds the line indicating the end of the header in a master
3017 file (@code{TeX-header-end}), it can figure out for itself that this is
3018 a master file. Otherwise, it will ask for the name of the master file
3019 associated with the buffer. To avoid asking you again, @AUCTeX{} will
3020 automatically insert the name of the master file as a file variable
3021 (@pxref{File Variables,,,emacs,The Emacs Editor}). You can also insert
3022 the file variable yourself, by putting the following text at the end of
3024 @findex TeX-header-end
3027 %%% Local Variables:
3028 %%% TeX-master: "master"
3032 You should always set this variable to the name of the top level document. If
3033 you always use the same name for your top level documents, you can set
3034 @code{TeX-master} in your @file{.emacs} file.
3037 (setq-default TeX-master "master") ; All master files called "master".
3041 The master file associated with the current buffer. If the file being
3042 edited is actually included from another file, then you can tell @AUCTeX{}
3043 the name of the master file by setting this variable. If there are
3044 multiple levels of nesting, specify the top level file.
3046 If this variable is @code{nil}, @AUCTeX{} will query you for the
3049 If the variable is @code{t}, then @AUCTeX{} will assume the file is a master
3052 If the variable is @code{shared}, then @AUCTeX{} will query for the name,
3053 but will not change the file.
3056 @defopt TeX-one-master
3057 Regular expression matching ordinary @TeX{} files.
3059 You should set this variable to match the name of all files, for which
3060 it is a good idea to append a @code{TeX-master} file variable entry
3061 automatically. When @AUCTeX{} adds the name of the master file as a
3062 file variable, it does not need to ask next time you edit the file.
3064 If you dislike @AUCTeX{} automatically modifying your files, you can
3065 set this variable to @samp{"<none>"}. By default, @AUCTeX{} will modify
3066 any file with an extension of @samp{.tex}.
3069 @deffn Command TeX-master-file-ask
3071 (@kbd{C-c _}) Query for the name of a master file and add the respective
3072 File Variables (@pxref{File Variables,,,emacs,The Emacs Editor}) to the
3073 file for setting this variable permanently.
3075 @AUCTeX{} will not ask for a master file when it encounters existing
3076 files. This function shall give you the possibility to insert the
3080 @AUCTeX{} keeps track of macros, environments, labels, and style
3081 files that are used in a given document. For this to work with
3082 multifile documents, @AUCTeX{} has to have a place to put the
3083 information about the files in the document. This is done by having an
3084 @file{auto} subdirectory placed in the directory where your document is
3085 located. Each time you save a file, @AUCTeX{} will write information
3086 about the file into the @file{auto} directory. When you load a file,
3087 @AUCTeX{} will read the information in the @file{auto} directory
3088 about the file you loaded @emph{and the master file specified by
3089 @code{TeX-master}}. Since the master file (perhaps indirectly) includes
3090 all other files in the document, @AUCTeX{} will get information from
3091 all files in the document. This means that you will get from each file,
3092 for example, completion for all labels defined anywhere in the document.
3094 @AUCTeX{} will create the @file{auto} directory automatically if
3095 @code{TeX-auto-save} is non-nil. Without it, the files in the document
3096 will not know anything about each other, except for the name of the
3097 master file. @xref{Automatic Local}.
3099 @deffn Command TeX-save-document
3101 (@kbd{C-c C-d}) Save all buffers known to belong to the current document.
3104 @defopt TeX-save-query
3105 If non-nil, then query the user before saving each file with
3106 @code{TeX-save-document}.
3111 @section Automatic Parsing of @TeX{} Files
3112 @cindex Parsing @TeX{}
3113 @cindex Automatic Parsing
3118 @AUCTeX{} depends heavily on being able to extract information from the
3119 buffers by parsing them. Since parsing the buffer can be somewhat slow,
3120 the parsing is initially disabled. You are encouraged to enable them by
3121 adding the following lines to your @file{.emacs} file.
3124 (setq TeX-parse-self t) ; Enable parse on load.
3125 (setq TeX-auto-save t) ; Enable parse on save.
3128 The latter command will make @AUCTeX{} store the parsed information in
3129 an @file{auto} subdirectory in the directory each time the @TeX{} files
3130 are stored, @pxref{Automatic Local}. If @AUCTeX{} finds the pre-parsed
3131 information when loading a file, it will not need to reparse the buffer.
3132 The information in the @file{auto} directory is also useful for
3133 multifile documents, @pxref{Multifile}, since it allows each file to
3134 access the parsed information from all the other files in the document.
3135 This is done by first reading the information from the master file, and
3136 then recursively the information from each file stored in the master
3139 The variables can also be done on a per file basis, by changing the file
3143 %%% Local Variables:
3144 %%% TeX-parse-self: t
3145 %%% TeX-auto-save: t
3149 Even when you have disabled the automatic parsing, you can force the
3150 generation of style information by pressing @kbd{C-c C-n}. This is
3151 often the best choice, as you will be able to decide when it is
3152 necessary to reparse the file.
3154 @defopt TeX-parse-self
3155 Parse file after loading it if no style hook is found for it.
3158 @defopt TeX-auto-save
3159 Automatically save style information when saving the buffer.
3162 @deffn Command TeX-normal-mode @var{arg}
3164 (@kbd{C-c C-n}) Remove all information about this buffer, and apply the
3165 style hooks again. Save buffer first including style information. With
3166 optional argument, also reload the style hooks.
3169 When @AUCTeX{} saves your buffer, it can optionally convert all tabs in
3170 your buffer into spaces.
3171 Tabs confuse @AUCTeX{}'s error message parsing and so should generally be
3172 avoided. However, tabs are significant in some environments, and so by
3173 default @AUCTeX{} does not remove them.
3174 To convert tabs to spaces when saving a buffer, insert the
3175 following in your @file{.emacs} file:
3178 (setq TeX-auto-untabify t)
3181 @defopt TeX-auto-untabify
3182 Automatically remove all tabs from a file before saving it.
3185 Instead of disabling the parsing entirely, you can also speed it
3186 significantly up by limiting the information it will search for (and
3187 store) when parsing the buffer. You can do this by setting the default
3188 values for the buffer local variables @code{TeX-auto-regexp-list} and
3189 @code{TeX-auto-parse-length} in your @file{.emacs} file.
3192 ;; Only parse LaTeX class and package information.
3193 (setq-default TeX-auto-regexp-list 'LaTeX-auto-minimal-regexp-list)
3194 ;; The class and package information is usually near the beginning.
3195 (setq-default TeX-auto-parse-length 2000)
3198 This example will speed the parsing up significantly, but @AUCTeX{}
3199 will no longer be able to provide completion for labels, macros,
3200 environments, or bibitems specified in the document, nor will it know
3201 what files belong to the document.
3203 These variables can also be specified on a per file basis, by changing
3204 the file local variables.
3207 %%% Local Variables:
3208 %%% TeX-auto-regexp-list: TeX-auto-full-regexp-list
3209 %%% TeX-auto-parse-length: 999999
3213 @defopt TeX-auto-regexp-list
3214 List of regular expressions used for parsing the current file.
3217 @defopt TeX-auto-parse-length
3218 Maximal length of @TeX{} file that will be parsed.
3221 The pre-specified lists of regexps are defined below. You can use these
3222 before loading @AUCTeX{} by quoting them, as in the example above.
3224 @defvr Constant TeX-auto-empty-regexp-list
3228 @defvr Constant LaTeX-auto-minimal-regexp-list
3229 Only parse @LaTeX{} class and packages.
3232 @defvr Constant LaTeX-auto-label-regexp-list
3233 Only parse @LaTeX{} labels.
3236 @defvr Constant LaTeX-auto-regexp-list
3237 Parse common @LaTeX{} commands.
3240 @defvr Constant plain-TeX-auto-regexp-list
3241 Parse common plain @TeX{} commands.
3244 @defvr Constant TeX-auto-full-regexp-list
3245 Parse all @TeX{} and @LaTeX{} commands that @AUCTeX{} can use.
3248 @node Internationalization
3249 @section Language Support
3250 @cindex Internationalization
3251 @cindex Language Support
3252 @cindex Character set
3253 @cindex National letters
3254 @cindex CJK language
3259 @cindex ASCII p@TeX{}
3264 @cindex CJK-@LaTeX{}
3268 @TeX{} and Emacs are usable for European (Latin, Cyrillic, Greek) based
3269 languages. Some @LaTeX{} and EmacsLisp packages are available for easy
3270 typesetting and editing documents in European languages.
3272 @c Some Texinfo macros are not used because they require quite recent
3273 @c texinfo versions (2005-03-05):
3274 @c Second arg of @acronym is available with 4.7, @comma is available in
3275 @c 4.7, @abbr is available in 4.8.
3276 @c -> @abbr{MULE, MULtilingual Enhancement to GNU Emacs}
3277 @c -> @acronym{CJK, Chinese@comma{} Japanese@comma{} and Korean}
3279 For @acronym{CJK} (Chinese, Japanese, and Korean) languages, Emacs or
3280 XEmacs with @acronym{MULE} (MULtilingual Enhancement to GNU Emacs)
3281 support is required. @acronym{MULE} is part of Emacs by default since
3282 Emacs 20. XEmacs has to be configured with the @samp{--with-mule}
3283 option. Special versions of @TeX{} are needed for @acronym{CJK}
3284 languages: C@TeX{} and China@TeX{} for Chinese, ASCII p@TeX{} and NTT
3285 j@TeX{} for Japanese, H@LaTeX{} and k@TeX{} for Korean. The
3286 @acronym{CJK}-@LaTeX{} package is required for supporting multiple
3287 @acronym{CJK} scripts within a single document.
3289 Note that Unicode is not fully supported in Emacs 21 and XEmacs 21.
3290 @acronym{CJK} characters are not usable. Please use the
3291 @acronym{MULE}-@acronym{UCS} EmacsLisp package or Emacs 22 (not released
3292 yet) if you need @acronym{CJK}.
3294 @c FIXME: We need more information for CTeX, ChinaTeX, KTeX, and HLaTeX.
3297 * European:: Using @AUCTeX{} with European Languages
3298 * Japanese:: Using @AUCTeX{} with Japanese
3302 @subsection Using @AUCTeX{} with European Languages
3304 @cindex European Characters
3305 @cindex ISO 8859 Latin 1
3307 @cindex ISO 8859 Latin 2
3311 @subsubsection Typing and Displaying Non-ASCII Characters
3313 First you will need a way to write non-ASCII characters. You can either
3314 use macros, or teach @TeX{} about the ISO character sets. I prefer the
3315 latter, it has the advantage that the usual standard emacs word
3316 movement and case change commands will work.
3318 With @LaTeX{}2e, just add @samp{\usepackage[latin1]@{inputenc@}}. Other
3319 languages than Western European ones will probably have other encoding
3322 To be able to display non-ASCII characters you will need an appropriate
3323 font and a version of GNU Emacs capable of displaying 8-bit characters
3324 (e.g. Emacs 21). The manner in which this is supported differs between
3325 Emacsen, so you need to take a look at your respective documentation.
3327 A compromise is to use an European character set when editing the file,
3328 and convert to @TeX{} macros when reading and writing the files.
3332 @cindex @file{iso-cvt.el}
3333 Much like @file{iso-tex.el} but is bundled with Emacs 19.23 and later.
3336 @cindex @file{x-compose.el}
3337 Similar package bundled with new versions of XEmacs.
3341 a much more complete package for both Emacs and XEmacs that can also
3342 handle a lot of mathematical characters and input methods.
3345 @subsubsection Style Files for Different Languages
3348 @AUCTeX{} supports style files for several languages. Each style file
3349 may modify @AUCTeX{} to better support the language, and will run
3350 a language specific hook that will allow you to for example change
3351 ispell dictionary, or run code to change the keyboard remapping. The
3352 following will for example choose a Danish dictionary for documents
3353 including @samp{\usepackage[danish]@{babel@}}.
3354 This requires parsing to be enabled, @pxref{Parsing Files}.
3357 (add-hook 'TeX-language-dk-hook
3358 (lambda () (ispell-change-dictionary "danish")))
3361 The following style files are recognized:
3363 @c In alphabetic order of the hooks:
3364 @vindex TeX-language-bg-hook
3365 @vindex TeX-language-cz-hook
3366 @vindex TeX-language-dk-hook
3367 @vindex TeX-language-nl-hook
3368 @vindex TeX-language-de-hook
3369 @vindex TeX-language-it-hook
3370 @vindex TeX-language-is-hook
3371 @vindex TeX-language-pl-hook
3372 @vindex TeX-language-sk-hook
3373 @vindex TeX-language-sv-hook
3385 Runs style hook @code{TeX-language-bg-hook}. Gives @samp{"} word
3386 syntax, makes the @key{"} key insert a literal @samp{"}. Typing @key{"}
3387 twice will insert insert @samp{"`} or @samp{"'} depending on context.
3388 Typing @key{-} twice will insert @samp{"=}, three times @samp{--}.
3391 Runs style hook @code{TeX-language-cz-hook}. Pressing @key{"} will
3392 insert @samp{\uv@{} and @samp{@}} depending on context.
3394 @c Is the difference between dk and danish really intented?
3396 Runs style hook @code{TeX-language-dk-hook}. Pressing @key{"} will
3397 insert @samp{"`} and @samp{"'} depending on context. Typing @key{-}
3398 twice will insert @samp{"=}, i.e. a hyphen string allowing hyphenation
3399 in the composing words.
3400 @c dk.sty seems to be obsolete, so we don't want to encourage using it.
3402 @c Runs style hook @code{TeX-language-dk-hook}.
3405 Runs style hook @code{TeX-language-nl-hook}.
3409 Runs style hook @code{TeX-language-de-hook}. Gives @samp{"} word
3410 syntax, makes the @key{"} key insert a literal @samp{"}. Pressing the
3411 key twice will give you opening or closing German quotes (@samp{"`} or
3412 @samp{"'}). Typing @key{-} twice will insert @samp{"=}, three times
3417 Runs style hook @code{TeX-language-fr-hook}. Pressing @key{"} will
3418 insert @samp{\\og} and @samp{\\fg} depending on context. Note that the
3419 language name for customizing @code{TeX-quote-language-alist} is
3423 Runs style hook @code{TeX-language-is-hook}. Gives @samp{"} word
3424 syntax, makes the @key{"} key insert a literal @samp{"}. Typing @key{"}
3425 twice will insert insert @samp{"`} or @samp{"'} depending on context.
3426 Typing @key{-} twice will insert @samp{"=}, three times @samp{--}.
3429 Runs style hook @code{TeX-language-it-hook}. Pressing @key{"} will
3430 insert @samp{"<} and @samp{">} depending on context.
3433 Runs style hook @code{TeX-language-pl-hook}. Gives @samp{"} word syntax
3434 and makes the @key{"} key insert a literal @samp{"}. Pressing @key{"}
3435 twice will insert @samp{"`} or @samp{"'} depending on context.
3438 Runs style hook @code{TeX-language-pl-hook}. Makes the @key{"} key
3439 insert a literal @samp{"}. Pressing @key{"} twice will insert @samp{,,}
3440 or @samp{''} depending on context.
3443 Runs style hook @code{TeX-language-sk-hook}. Pressing @key{"} will
3444 insert @samp{\uv@{} and @samp{@}} depending on context.
3447 Runs style hook @code{TeX-language-sv-hook}. Pressing @key{"} will
3448 insert @samp{''}. Typing @key{-} twice will insert @samp{"=}, three
3452 Replacement of language-specific hyphen strings like @samp{"=} with
3453 dashes does not require to type @key{-} three times in a row. You can
3454 put point after the hypen string anytime and trigger the replacement by
3457 In case you are not satisfied with the suggested behavior of quote and
3458 hyphen insertion you can change it by customizing the variables
3459 @code{TeX-quote-language-alist} and
3460 @code{LaTeX-babel-hyphen-language-alist} respectively.
3462 @defopt TeX-quote-language-alist
3463 Used for overriding the default language-specific quote insertion
3464 behavior. This is an alist where each element is a list consisting of
3465 four items. The first item is the name of the language in concern as a
3466 string. See the list of supported languages above. The second item is
3467 the opening quotation mark. The third item is the closing quotation
3468 mark. Opening and closing quotation marks can be specified directly as
3469 strings or as functions returning a string. The fourth item is a
3470 boolean controlling quote insertion. It should be non-nil if if the
3471 special quotes should only be used after inserting a literal @samp{"}
3472 character first, i.e. on second key press.
3475 @defopt LaTeX-babel-hyphen-language-alist
3476 Used for overriding the behavior of hyphen insertion for specific
3477 languages. Every element in this alist is a list of three items. The
3478 first item should specify the affected language as a string. The second
3479 item denotes the hyphen string to be used as a string. The third item,
3480 a boolean, controls the behavior of hyphen insertion and should be
3481 non-nil if the special hyphen should be inserted after inserting a
3482 literal @samp{-} character, i.e. on second key press.
3485 The defaults of hyphen insertion are defined by the variables
3486 @code{LaTeX-babel-hyphen} and @code{LaTeX-babel-hyphen-after-hyphen}
3489 @defopt LaTeX-babel-hyphen
3490 String to be used when typing @key{-}. This usually is a hyphen
3491 alternative or hyphenation aid provided by @samp{babel} and the related
3492 language style files, like @samp{"=}, @samp{"~} or @samp{"-}.
3494 Set it to an empty string or nil in order to disable language-specific
3498 @defopt LaTeX-babel-hyphen-after-hyphen
3499 Control insertion of hyphen strings. If non-nil insert normal hyphen on
3500 first key press and swap it with the language-specific hyphen string
3501 specified in the variable @code{LaTeX-babel-hyphen} on second key press.
3502 If nil do it the other way round.
3506 @subsection Using @AUCTeX{} with Japanese @TeX{}
3514 @cindex ASCII p@TeX{}
3517 @cindex @file{tex-jp.el}
3518 @vindex TeX-default-mode
3519 @vindex japanese-TeX-command-default
3520 @vindex japanese-LaTeX-command-default
3521 @vindex japanese-LaTeX-default-style
3523 To write Japanese text with @AUCTeX{}, you need to have versions of
3524 @TeX{} and Emacs that support Japanese. There exist at least two
3525 variants of @TeX{} for Japanese text (NTT j@TeX{} and ASCII p@TeX{}).
3526 @AUCTeX{} can be used with @acronym{MULE, MULtilingual Enhancement to GNU
3527 Emacs} supported Emacsen.
3529 To use the Japanese @TeX{} variants, simply activate
3530 @code{japanese-plain-tex-mode} or @code{japanese-latex-mode} and
3531 everything should work. If not, send mail to Masayuki Ataka
3532 @samp{<ataka@@milk.freemail.ne.jp>}, who kindly donated the code for
3533 supporting Japanese in @AUCTeX{}. None of the primary @AUCTeX{}
3534 maintainers understand Japanese, so they cannot help you.
3536 If you usually use @AUCTeX{} in Japanese, setting the following
3537 variables is useful.
3539 @defopt TeX-default-mode
3540 Mode to enter for a new file when it cannott be determined whether the
3541 file is plain @TeX{} or @LaTeX{} or what.
3543 If you want to enter Japanese @LaTeX{} mode whenever this may happen,
3544 set the variable like this:
3546 (setq TeX-default-mode 'japanese-latex-mode)
3550 @defopt japanese-TeX-command-default
3551 The default command for @code{TeX-command} in Japanese @TeX{} mode.
3553 The default value is @samp{"pTeX"}.
3556 @defopt japanese-LaTeX-command-default
3557 The default command for @code{TeX-command} in Japanese @LaTeX{} mode.
3559 The default value is @samp{"LaTeX"}.
3562 @defopt japanese-LaTeX-default-style
3563 The default style/class when creating a new Japanese @LaTeX{} document.
3565 The default value is @samp{"jarticle"}.
3568 See @file{tex-jp.el} for more information.
3571 @section Automatic Customization
3572 @cindex Automatic Customization
3573 @cindex Extracting @TeX{} symbols
3575 @cindex @file{auto} directories.
3576 @cindex Parsing @TeX{}
3577 @cindex @TeX{} parsing
3578 @cindex Generating symbols
3580 Since @AUCTeX{} is so highly customizable, it makes sense that it is able
3581 to customize itself. The automatic customization consists of scanning
3582 @TeX{} files and extracting symbols, environments, and things like that.
3584 The automatic customization is done on three different levels. The
3585 global level is the level shared by all users at your site, and consists
3586 of scanning the standard @TeX{} style files, and any extra styles added
3587 locally for all users on the site. The private level deals with those
3588 style files you have written for your own use, and use in different
3589 documents. You may have a @file{~/lib/TeX/} directory where you store
3590 useful style files for your own use. The local level is for a specific
3591 directory, and deals with writing customization for the files for your
3592 normal @TeX{} documents.
3594 If compared with the environment variable @code{TEXINPUTS}, the
3595 global level corresponds to the directories built into @TeX{}. The
3596 private level corresponds to the directories you add yourself, except for
3597 @file{.}, which is the local level.
3600 * Automatic Global:: Automatic Customization for the Site
3601 * Automatic Private:: Automatic Customization for a User
3602 * Automatic Local:: Automatic Customization for a Directory
3605 By default @AUCTeX{} will search for customization files in all the
3606 global, private, and local style directories, but you can also set the
3607 path directly. This is useful if you for example want to add another
3608 person's style hooks to your path. Please note that all matching files
3609 found in @code{TeX-style-path} are loaded, and all hooks defined in the
3610 files will be executed.
3612 @defopt TeX-style-path
3613 List of directories to search for @AUCTeX{} style files.
3614 Each must end with a slash.
3617 By default, when @AUCTeX{} searches a directory for files, it will
3618 recursively search through subdirectories.
3620 @defopt TeX-file-recurse
3621 Whether to search @TeX{} directories recursively: nil means do not
3622 recurse, a positive integer means go that far deep in the directory
3623 hierarchy, t means recurse indefinitely.
3626 By default, @AUCTeX{} will ignore files named @file{.}, @file{..},
3627 @file{SCCS}, @file{RCS}, and @file{CVS}.
3629 @defopt TeX-ignore-file
3630 Regular expression matching file names to ignore.
3632 These files or directories will not be considered when searching for
3633 @TeX{} files in a directory.
3636 @node Automatic Global
3637 @subsection Automatic Customization for the Site
3638 @cindex Global style hook directory
3639 @cindex Global macro directory
3640 @cindex Site macro directory
3641 @cindex Global @TeX{} macro directory
3642 @cindex Site @TeX{} macro directory
3643 @cindex Global directories
3644 @cindex Site information
3646 Assuming that the automatic customization at the global level was done
3647 when @AUCTeX{} was installed, your choice is now: will you use it? If
3648 you use it, you will benefit by having access to all the symbols and
3649 environments available for completion purposes. The drawback is slower
3650 load time when you edit a new file and perhaps too many confusing
3651 symbols when you try to do a completion.
3653 You can disable the automatic generated global style hooks by setting
3654 the variable @code{TeX-auto-global} to nil.
3656 @defopt TeX-macro-global
3657 Directories containing the site's @TeX{} style files.
3660 @defopt TeX-style-global
3661 Directory containing hand generated @TeX{} information.
3662 Must end with a slash.
3664 These correspond to @TeX{} macros shared by all users of a site.
3667 @defopt TeX-auto-global
3668 Directory containing automatically generated information.
3670 For storing automatic extracted information about the @TeX{} macros
3671 shared by all users of a site.
3674 @node Automatic Private
3675 @subsection Automatic Customization for a User
3676 @cindex Private style hook directory
3677 @cindex Private macro directory
3678 @cindex Personal macro directory
3679 @cindex Private @TeX{} macro directory
3680 @cindex Personal @TeX{} macro directory
3681 @cindex Private directories
3682 @cindex Personal information
3684 You should specify where you store your private @TeX{} macros, so
3685 @AUCTeX{} can extract their information. The extracted information will
3686 go to the directories listed in @code{TeX-auto-private}
3688 Use @kbd{M-x TeX-auto-generate @key{RET}} to extract the information.
3690 @defopt TeX-macro-private
3691 Directories where you store your personal @TeX{} macros. The value
3692 defaults to the directories listed in the @samp{TEXINPUTS} and
3693 @samp{BIBINPUTS} environment variables or to the respective directories
3694 in @code{$TEXMFHOME} if no results can be obtained from the environment
3698 @defopt TeX-auto-private
3699 List of directories containing automatically generated @AUCTeX{} style
3700 files. These correspond to the personal @TeX{} macros.
3703 @deffn Command TeX-auto-generate @var{TEX} @var{AUTO}
3704 (@kbd{M-x TeX-auto-generate @key{RET}}) Generate style hook for
3705 @var{TEX} and store it in @var{AUTO}. If @var{TEX} is a directory,
3706 generate style hooks for all files in the directory.
3709 @defopt TeX-style-private
3710 List of directories containing hand generated @AUCTeX{} style files.
3711 These correspond to the personal @TeX{} macros.
3714 @node Automatic Local
3715 @subsection Automatic Customization for a Directory
3716 @cindex Local style hooks
3717 @cindex Updating style hooks
3718 @cindex Automatic updating style hooks
3719 @cindex Local style hooks
3720 @cindex Local style directory
3722 @AUCTeX{} can update the style information about a file each time you
3723 save it, and it will do this if the directory @code{TeX-auto-local}
3724 exist. @code{TeX-auto-local} is by default set to @samp{"auto"}, so
3725 simply creating an @file{auto} directory will enable automatic saving of
3728 The advantage of doing this is that macros, labels, etc. defined in any
3729 file in a multifile document will be known in all the files in the
3730 document. The disadvantage is that saving will be slower. To disable,
3731 set @code{TeX-auto-local} to nil.
3733 @defopt TeX-style-local
3734 Directory containing hand generated @TeX{} information.
3735 Must end with a slash.
3737 These correspond to @TeX{} macros found in the current directory.
3740 @defopt TeX-auto-local
3741 Directory containing automatically generated @TeX{} information.
3742 Must end with a slash.
3744 These correspond to @TeX{} macros found in the current directory.
3748 @section Writing Your Own Style Support
3751 @cindex @file{style}
3753 @xref{Automatic}, for a discussion about automatically generated global,
3754 private, and local style files. The hand generated style files are
3755 equivalent, except that they by default are found in @file{style}
3756 directories instead of @file{auto} directories.
3759 * Simple Style:: A Simple Style File
3760 * Adding Macros:: Adding Support for Macros
3761 * Adding Environments:: Adding Support for Environments
3762 * Adding Other:: Adding Other Information
3763 * Hacking the Parser:: Automatic Extraction of New Things
3766 If you write some useful support for a public @TeX{} style file, please
3770 @subsection A Simple Style File
3771 @cindex @file{book.el}
3772 @cindex Sample style file
3774 @cindex Example of a style file.
3776 @cindex Adding a style hook
3778 Here is a simple example of a style file.
3781 ;;; book.el - Special code for book style.
3786 (LaTeX-largest-level-set "chapter")))
3789 The example is from the @AUCTeX{} sources and is loaded for any @LaTeX{}
3790 document using the book document class (or style before @LaTeX{}2e).
3791 The file specifies that the largest kind of section in such a document
3792 is chapter. The interesting thing to notice is that the style file
3793 defines an (anonymous) function, and adds it to the list of loaded style
3794 hooks by calling @code{TeX-add-style-hook}.
3796 The first time the user indirectly tries to access some style-specific
3797 information, such as the largest sectioning command available, the style
3798 hooks for all files directly or indirectly read by the current document
3799 are executed. The actual files will only be evaluated once, but the
3800 hooks will be called for each buffer using the style file.
3802 Note that the basename of the style file and the name of the style hook
3803 should usually be identical.
3805 @defun TeX-add-style-hook @var{style} @var{hook}
3806 Add @var{hook} to the list of functions to run when we use the @TeX{}
3811 @subsection Adding Support for Macros
3812 @cindex Adding macros
3813 @cindex Macros, adding
3814 @cindex Defining macros in style hooks
3816 The most common thing to define in a style hook is new symbols (@TeX{}
3817 macros). Most likely along with a description of the arguments to the
3818 function, since the symbol itself can be defined automatically.
3820 Here are a few examples from @file{latex.el}.
3827 '("arabic" TeX-arg-counter)
3828 '("label" TeX-arg-define-label)
3829 '("ref" TeX-arg-label)
3830 '("newcommand" TeX-arg-define-macro [ "Number of arguments" ] t)
3831 '("newtheorem" TeX-arg-define-environment
3832 [ TeX-arg-environment "Numbered like" ]
3833 t [ TeX-arg-counter "Within counter" ]))))
3836 @defun TeX-add-symbols @var{symbol} @dots{}
3837 Add each @var{symbol} to the list of known symbols.
3840 Each argument to @code{TeX-add-symbols} is a list describing one symbol.
3841 The head of the list is the name of the symbol, the remaining elements
3842 describe each argument.
3844 If there are no additional elements, the symbol will be inserted with
3845 point inside braces. Otherwise, each argument of this function should
3846 match an argument of the @TeX{} macro. What is done depends on the argument
3849 If a macro is defined multiple times, @AUCTeX{} will chose the one with
3850 the longest definition (i.e. the one with the most arguments).
3854 '("tref" 1) ; one argument
3858 '("tref" TeX-arg-label ignore) ; two arguments
3861 @code{ignore} is a function that does not do anything, so when you
3862 insert a @samp{tref} you will be prompted for a label and no more.
3864 You can use the following types of specifiers for arguments:
3868 Use the string as a prompt to prompt for the argument.
3871 Insert that many braces, leave point inside the first. 0 and -1 are
3872 special. 0 means that no braces are inserted. -1 means that braces are
3873 inserted around the macro and an active region (e.g. @samp{@{\tiny
3874 foo@}}). If there is no active region, no braces are inserted.
3877 Insert empty braces.
3880 Insert empty braces, leave point between the braces.
3883 Call the symbol as a function. You can define your
3884 own hook, or use one of the predefined argument hooks.
3887 If the car is a string, insert it as a prompt and the next
3888 element as initial input. Otherwise, call the car of the list with
3889 the remaining elements as arguments.
3892 Optional argument. If it has more than one element, parse it
3893 as a list, otherwise parse the only element as above. Use square
3894 brackets instead of curly braces, and is not inserted on empty user
3898 A lot of argument hooks have already been defined. The first argument to
3899 all hooks is a flag indicating if it is an optional argument. It is up
3900 to the hook to determine what to do with the remaining arguments, if
3901 any. Typically the next argument is used to overwrite the default
3905 @item TeX-arg-conditional
3906 Implements if EXPR THEN ELSE. If EXPR evaluates to true, parse THEN as an
3907 argument list, else parse ELSE as an argument list.
3909 @item TeX-arg-literal
3910 Insert its arguments into the buffer. Used for specifying extra syntax
3914 Parse its arguments but use no braces when they are inserted.
3917 Evaluate arguments and insert the result in the buffer.
3920 Prompt for a label completing with known labels.
3923 Prompt for a @TeX{} macro with completion.
3925 @item TeX-arg-environment
3926 Prompt for a @LaTeX{} environment with completion.
3929 Prompt for a Bib@TeX{} citation.
3931 @item TeX-arg-counter
3932 Prompt for a @LaTeX{} counter.
3934 @item TeX-arg-savebox
3935 Prompt for a @LaTeX{} savebox.
3938 Prompt for a filename in the current directory, and use it without the
3941 @item TeX-arg-input-file
3942 @vindex TeX-arg-input-file-search
3943 Prompt for the name of an input file in @TeX{}'s search path, and use it
3944 without the extension. Run the style hooks for the file. (Note that
3945 the behavior (type of prompt and inserted file name) of the function can
3946 be controlled by the variable @code{TeX-arg-input-file-search}.)
3948 @item TeX-arg-define-label
3949 Prompt for a label completing with known labels. Add label to list of
3952 @item TeX-arg-define-macro
3953 Prompt for a @TeX{} macro with completion. Add macro to list of defined
3956 @item TeX-arg-define-environment
3957 Prompt for a @LaTeX{} environment with completion. Add environment to
3958 list of defined environments.
3960 @item TeX-arg-define-cite
3961 Prompt for a Bib@TeX{} citation.
3963 @item TeX-arg-define-counter
3964 Prompt for a @LaTeX{} counter.
3966 @item TeX-arg-define-savebox
3967 Prompt for a @LaTeX{} savebox.
3969 @item TeX-arg-corner
3970 Prompt for a @LaTeX{} side or corner position with completion.
3973 Prompt for a @LaTeX{} side with completion.
3976 Prompt for a @LaTeX{} side with completion.
3978 @item TeX-arg-pagestyle
3979 Prompt for a @LaTeX{} pagestyle with completion.
3982 Prompt for delimiter and text.
3985 Insert a pair of numbers, use arguments for prompt. The numbers are
3986 surrounded by parentheses and separated with a comma.
3989 Insert width and height as a pair. No arguments.
3991 @item TeX-arg-coordinate
3992 Insert x and y coordinates as a pair. No arguments.
3995 If you add new hooks, you can assume that point is placed directly after
3996 the previous argument, or after the macro name if this is the first
3997 argument. Please leave point located after the argument you are
3998 inserting. If you want point to be located somewhere else after all
3999 hooks have been processed, set the value of @code{exit-mark}. It will
4000 point nowhere, until the argument hook sets it.
4002 @node Adding Environments
4003 @subsection Adding Support for Environments
4004 @cindex Adding environments
4005 @cindex Environments, adding
4006 @cindex Defining environments in style hooks
4008 Adding support for environments is very much like adding support for
4009 @TeX{} macros, except that each environment normally only takes one
4010 argument, an environment hook. The example is again a short version of
4017 (LaTeX-add-environments
4018 '("document" LaTeX-env-document)
4019 '("enumerate" LaTeX-env-item)
4020 '("itemize" LaTeX-env-item)
4021 '("list" LaTeX-env-list))))
4024 It is completely up to the environment hook to insert the environment,
4025 but the function @code{LaTeX-insert-environment} may be of some help.
4026 The hook will be called with the name of the environment as its first
4027 argument, and extra arguments can be provided by adding them to a list
4030 For simple environments with arguments, for example defined with
4031 @samp{\newenvironment}, you can make @AUCTeX{} prompt for the arguments
4032 by giving the prompt strings in the call to
4033 @code{LaTeX-add-environments}. The fact that an argument is optional
4034 can be indicated by wrapping the prompt string in a vector.
4036 For example, if you have defined a @code{loop} environment with the
4037 three arguments @var{from}, @var{to}, and @var{step}, you can add
4038 support for them in a style file.
4043 \newenvironment@{loop@}[3]@{...@}@{...@}
4052 (LaTeX-add-environments
4053 '("loop" "From" "To" "Step"))))
4056 If an environment is defined multiple times, @AUCTeX{} will choose the
4057 one with the longest definition. Thus, if you have an enumerate style
4058 file, and want it to replace the standard @LaTeX{} enumerate hook above,
4059 you could define an @file{enumerate.el} file as follows, and place it in
4060 the appropriate style directory.
4066 (LaTeX-add-environments
4067 '("enumerate" LaTeX-env-enumerate foo))))
4069 (defun LaTeX-env-enumerate (environment &optional ignore) ...)
4072 The symbol @code{foo} will be passed to @code{LaTeX-env-enumerate} as
4073 the second argument, but since we only added it to overwrite the
4074 definition in @file{latex.el} it is just ignored.
4076 @defun LaTeX-add-environments @var{env} @dots{}
4077 Add each @var{env} to list of loaded environments.
4080 @defun LaTeX-insert-environment @var{env} [ @var{extra} ]
4081 Insert environment of type @var{env}, with optional argument @var{extra}.
4084 Following is a list of available hooks for
4085 @code{LaTeX-add-environments}:
4088 @item LaTeX-env-item
4089 Insert the given environment and the first item.
4091 @item LaTeX-env-figure
4092 Insert the given figure-like environment with a caption and a label.
4094 @item LaTeX-env-array
4095 Insert the given array-like environment with position and column
4098 @item LaTeX-env-label
4099 Insert the given environment with a label.
4101 @item LaTeX-env-list
4102 Insert the given list-like environment, a specifier for the label and
4105 @item LaTeX-env-minipage
4106 Insert the given minipage-like environment with position and width
4109 @item LaTeX-env-tabular*
4110 Insert the given tabular*-like environment with width, position and
4111 column specifications.
4113 @item LaTeX-env-picture
4114 Insert the given environment with width and height specifications.
4117 Insert the given environment with a label for a bibitem.
4119 @item LaTeX-env-contents
4120 Insert the given environment with a filename as its argument.
4122 @item LaTeX-env-args
4123 Insert the given environment with arguments. You can use this as a hook
4124 in case you want to specify multiple complex arguments just like in
4125 elements of @code{TeX-add-symbols}. This is most useful if the
4126 specification of arguments to be prompted for with strings and strings
4127 wrapped in a vector as described above is too limited.
4129 Here is an example from @file{listings.el} which calls a function with
4130 one argument in order to prompt for a key=value list to be inserted as
4131 an optional argument of the @samp{lstlisting} environment:
4134 (LaTeX-add-environments
4135 `("lstlisting" LaTeX-env-args
4136 [TeX-arg-key-val ,LaTeX-listings-key-val-options]))
4141 @subsection Adding Other Information
4142 @cindex Adding bibliographies
4143 @cindex Bibliographies, adding
4144 @cindex Defining bibliographies in style hooks
4145 @cindex Adding labels
4146 @cindex Labels, adding
4147 @cindex Defining labels in style hooks
4148 @cindex Adding other information
4149 @cindex Other information, adding
4150 @cindex Defining other information in style hooks
4152 You can also specify bibliographical databases and labels in the style
4153 file. This is probably of little use, since this information will
4154 usually be automatically generated from the @TeX{} file anyway.
4156 @defun LaTeX-add-bibliographies @var{bibliography} @dots{}
4157 Add each @var{bibliography} to list of loaded bibliographies.
4160 @defun LaTeX-add-labels @var{label} @dots{}
4161 Add each @var{label} to the list of known labels.
4164 @node Hacking the Parser
4165 @subsection Automatic Extraction of New Things
4166 @cindex Parsing new macros
4167 @cindex @file{macro.tex}
4168 @cindex @file{macro.el}
4169 @cindex Changing the parser
4171 The automatic @TeX{} information extractor works by searching for
4172 regular expressions in the @TeX{} files, and storing the matched
4173 information. You can add support for new constructs to the parser,
4174 something that is needed when you add new commands to define symbols.
4176 For example, in the file @file{macro.tex} I define the following macro.
4179 \newcommand@{\newmacro@}[5]@{%
4180 \def#1@{#3\index@{#4@@#5~cite@{#4@}@}\nocite@{#4@}@}%
4181 \def#2@{#5\index@{#4@@#5~cite@{#4@}@}\nocite@{#4@}@}%
4185 @AUCTeX{} will automatically figure out that @samp{newmacro} is a macro
4186 that takes five arguments. However, it is not smart enough to
4187 automatically see that each time we use the macro, two new macros are
4188 defined. We can specify this information in a style hook file.
4191 ;;; macro.el --- Special code for my own macro file.
4195 (defvar TeX-newmacro-regexp
4196 '("\\\\newmacro@{\\\\\\([a-zA-Z]+\\)@}@{\\\\\\([a-zA-Z]+\\)@}"
4197 (1 2) TeX-auto-multi)
4198 "Matches \newmacro definitions.")
4200 (defvar TeX-auto-multi nil
4201 "Temporary for parsing \\newmacro definitions.")
4203 (defun TeX-macro-cleanup ()
4204 "Move symbols from `TeX-auto-multi' to `TeX-auto-symbol'."
4205 (mapcar (lambda (list)
4206 (mapcar (lambda (symbol)
4207 (setq TeX-auto-symbol
4208 (cons symbol TeX-auto-symbol)))
4212 (defun TeX-macro-prepare ()
4213 "Clear `Tex-auto-multi' before use."
4214 (setq TeX-auto-multi nil))
4216 (add-hook 'TeX-auto-prepare-hook 'TeX-macro-prepare)
4217 (add-hook 'TeX-auto-cleanup-hook 'TeX-macro-cleanup)
4222 (TeX-auto-add-regexp TeX-newmacro-regexp)
4223 (TeX-add-symbols '("newmacro"
4225 (TeX-arg-macro "Capitalized macro: \\")
4230 ;;; macro.el ends here
4233 When this file is first loaded, it adds a new entry to
4234 @code{TeX-newmacro-regexp}, and defines a function to be called before
4235 the parsing starts, and one to be called after the parsing is done. It
4236 also declares a variable to contain the data collected during parsing.
4237 Finally, it adds a style hook which describes the @samp{newmacro} macro,
4238 as we have seen it before.
4240 So the general strategy is: Add a new entry to @code{TeX-newmacro-regexp}.
4241 Declare a variable to contain intermediate data during parsing. Add hook
4242 to be called before and after parsing. In this case, the hook before
4243 parsing just initializes the variable, and the hook after parsing
4244 collects the data from the variable, and adds them to the list of symbols
4247 @defvar TeX-auto-regexp-list
4248 List of regular expressions matching @TeX{} macro definitions.
4250 The list has the following format ((REGEXP MATCH TABLE) @dots{}), that
4251 is, each entry is a list with three elements.
4253 REGEXP. Regular expression matching the macro we want to parse.
4255 MATCH. A number or list of numbers, each representing one
4256 parenthesized subexpression matched by REGEXP.
4258 TABLE. The symbol table to store the data. This can be a function, in
4259 which case the function is called with the argument MATCH. Use
4260 @code{TeX-match-buffer} to get match data. If it is not a function, it
4261 is presumed to be the name of a variable containing a list of match
4262 data. The matched data (a string if MATCH is a number, a list of
4263 strings if MATCH is a list of numbers) is put in front of the table.
4266 @defvar TeX-auto-prepare-hook nil
4267 List of functions to be called before parsing a @TeX{} file.
4270 @defvar TeX-auto-cleanup-hook nil
4271 List of functions to be called after parsing a @TeX{} file.
4275 @appendix Copying, Changes, Development, FAQ, Texinfo Mode
4278 * Copying this Manual::
4285 @node Copying this Manual
4286 @appendixsec Copying this Manual
4289 The copyright notice for this manual is:
4294 The full license text can be read here:
4297 * GNU Free Documentation License:: License for copying this manual.
4305 @appendixsec Changes and New Features
4308 @include changes.texi
4311 @subheading Older versions
4312 See the file @file{history.texi} for older changes.
4315 @appendixsec Future Development
4322 @appendixsec Frequently Asked Questions
4329 @appendixsec Features specific to @AUCTeX{}'s Texinfo major mode
4331 @AUCTeX{} includes a major mode for editting Texinfo files. This major
4332 mode is not the same mode as the native Texinfo mode (@pxref{(texinfo)
4333 Texinfo Mode}) of Emacs, although they have the same name. However,
4334 @AUCTeX{} still relies on a number of functions from the native Texinfo
4337 The following text describes which functionality is offered by @AUCTeX{}
4338 and which by the native Texinfo mode. This should enable you to decide
4339 when to consult the @AUCTeX{} manual and when the manual of the native
4340 mode. And in case you are a seasoned user of the native mode, the
4341 information should help you to swiftly get to know the
4342 @AUCTeX{}-specific commands.
4345 * Exploiting:: How @AUCTeX{} and the native mode work together
4346 * Superseding:: Where the native mode is superseded
4347 * Mapping:: Where key bindings are mapped to the native mode
4348 * Unbinding:: Which native mode key bindings are missing
4352 @appendixsubsec How @AUCTeX{} and the native mode work together
4354 In a nutshell the split between @AUCTeX{} Texinfo mode, and native
4355 Texinfo mode is as follows:
4359 Most of the editing (environment creation, commenting, font command
4360 insertions) and/or processing commands (e.g. compiling or printing)
4361 which are available in other @AUCTeX{} modes are also handled by
4362 @AUCTeX{} in Texinfo mode.
4365 Texinfo-related features (e.g. info node linkage or menu creation) rely
4366 on the commands provided by the native Texinfo mode. @AUCTeX{} provides
4367 the key bindings to reach these functions, keeping the same keys as in
4368 native Texinfo whenever possible, or similar ones otherwise.
4372 @appendixsubsec Where the native mode is superseded
4374 This section is directed to users of the native Texinfo mode switching
4375 to @AUCTeX{}. It follows the summary of the native mode
4376 (@pxref{(texinfo) Texinfo Mode Summary}) and lists which of its commands
4377 are no longer of use.
4380 @item Insert commands
4381 In the native Texinfo mode, frequently used Texinfo commands can be
4382 inserted with key bindings of the form @kbd{C-c C-c @var{k}} where
4383 @var{k} differs for each Texinfo command; @kbd{c} inserts @@code,
4384 @kbd{d} inserts @@dfn, @kbd{k} @@kbd, etc.
4386 In @AUCTeX{} commands are inserted with the key binding @kbd{C-c C-m}
4387 instead which prompts for the macro to be inserted. For font selection
4388 commands (like @@b, @@i, or @@emph) and a few related ones (like @@var,
4389 @@key or @@code) there are bindings which insert the respective macros
4390 directly. They have the form @code{C-c C-f @var{k}} or @code{C-c C-f
4391 C-@var{k}} and call the function @code{TeX-font}. Type @kbd{C-c C-f
4392 @key{RET}} to get a list of supported commands.
4394 Note that the prefix argument is not handled the same way by @AUCTeX{}.
4395 Note also that the node insertion command from the native mode
4396 (@code{texinfo-insert-@@node}) can still accessed from the Texinfo menu
4400 In @AUCTeX{} braces can be inserted with the same key binding as in the
4401 native Texinfo mode: @kbd{C-c @{}. But @AUCTeX{} uses its own function
4402 for the feature: @code{TeX-insert-braces}.
4404 @item Insert environments
4405 The native Texinfo mode does not insert full environments. Instead, it
4406 provides the function @code{texinfo-insert-@@end} (mapped to @kbd{C-c
4407 C-c e}) for closing an open environment with a matching @@end statement.
4409 In @AUCTeX{} you can insert full environments, i.e. both the opening and
4410 closing statements, with the function @code{Texinfo-environment} (mapped
4413 @item Format info files with makeinfo and @TeX{}
4414 In the native Texinfo mode there are various functions and bindings to
4415 format a region or the whole buffer for info or to typeset the
4416 respective text. For example, there is @code{makeinfo-buffer} (mapped
4417 to @kbd{C-c C-m C-b}) which runs @samp{makeinfo} on the buffer or there
4418 is @code{texinfo-tex-buffer} (mapped to @kbd{C-c C-t C-b}) which runs
4419 @TeX{} on the buffer in order to produce a @acronym{DVI} file.
4421 In @AUCTeX{} different commands for formatting or typesetting can be
4422 invoked through the function @code{TeX-command-master} (mapped to
4423 @kbd{C-c C-c}). After typing @kbd{C-c C-c}, you can select the desired
4424 command, e.g @samp{Makeinfo} or @samp{TeX}, through a prompt in the mini
4425 buffer. Note that you can make, say @samp{Makeinfo}, the default by
4426 adding this statement in your init file:
4429 (add-hook 'Texinfo-mode-hook
4430 (lambda () (setq TeX-command-default "Makeinfo")))
4433 Note also that @kbd{C-c C-c Makeinfo @key{RET}} is not completely
4434 functionally equivalent to @code{makeinfo-buffer} as the latter will
4435 display the resulting info file in Emacs, showing the node corresponding
4436 to the position in the source file, just after a successful compilation.
4437 This is why, while using @AUCTeX{}, invoking @code{makeinfo-buffer}
4438 might still be more convenient.
4440 Note also that in the case of a multifile document, @kbd{C-c C-c} in
4441 @AUCTeX{} will work on the whole document (provided that the file
4442 variable @code{TeX-master} is set correctly), while
4443 @code{makeinfo-buffer} in the native mode will process only the current
4444 buffer, provided at the @code{@@setfilename} statement is provided.
4446 @item Produce indexes and print
4447 The native Texinfo mode provides the binding @kbd{C-c C-t C-i}
4448 (@code{texinfo-texindex}) for producing an index and the bindings
4449 @kbd{C-c C-t C-p} (@code{texinfo-tex-print}) and @kbd{C-c C-t C-q}
4450 (@code{tex-show-print-queue}) for printing and showing the printer
4451 queue. These are superseded by the respective commands available
4452 through @kbd{C-c C-c} (@code{TeX-command-master}) in @AUCTeX{}: Index,
4456 The command @kbd{C-c C-t C-k} (@code{tex-kill-job}) in the native mode
4457 is superseded by @kbd{C-c C-k} (@code{TeX-kill-job}) in @AUCTeX{}.
4461 @appendixsubsec Where key bindings are mapped to the native mode
4463 This node follows the native Texinfo mode summary (@pxref{(texinfo)
4464 Texinfo Mode Summary}) and lists only those commands to which @AUCTeX{}
4465 provides a keybinding.
4467 Basically all commands of the native mode related to producing menus and
4468 interlinking nodes are mapped to same or similar keys in @AUCTeX{},
4469 while a few insertion commands are mapped to @AUCTeX{}-like keys.
4473 @item @code{@@item} insertion
4474 The binding @kbd{C-c C-c i} for the insertion of @code{@@item} in the
4475 native mode is mapped to @kbd{M-@key{RET}} or @kbd{C-c C-j} in
4476 @AUCTeX{}, similar to other @AUCTeX{} modes.
4478 @item @code{@@end} insertion
4479 The binding @kbd{C-c C-c e} for closing a @code{@@@var{foo}} command by
4480 a corresponding @code{@@end @var{foo}} statement in the native mode is
4481 mapped to @kbd{C-c C-]} in @AUCTeX{}, similar to other @AUCTeX{} modes.
4483 @item Move out of balanced braces
4484 The binding @kbd{C-@}} (@code{up-list}) is available both in the native
4485 mode and in @AUCTeX{}. (This is because the command is not implemented
4486 in either mode but a native Emacs command.) However, in @AUCTeX{}, you
4487 cannot use @kbd{C-]} for this, as it is used for @code{@@end} insertion.
4489 @item Update pointers
4490 The bindings @kbd{C-c C-u C-n} (@code{texinfo-update-node}) and @kbd{C-c
4491 C-u C-e} (@code{texinfo-every-node-update}) from the native mode are
4492 available in @AUCTeX{} as well.
4495 The bindings @kbd{C-c C-u m} (@code{texinfo-master-menu}), @kbd{C-c C-u
4496 C-m} (@code{texinfo-make-menu}), and @kbd{C-c C-u C-a}
4497 (@code{texinfo-all-menus-update}) from the native mode are available in
4498 @AUCTeX{} as well. The command @code{texinfo-start-menu-description},
4499 bound to @kbd{C-c C-c C-d} in the native mode, is bound to @kbd{C-c C-u
4500 C-d} in @AUCTeX{} instead.
4504 @appendixsubsec Which native mode key bindings are missing
4506 The following commands from the native commands might still be useful
4507 when working with @AUCTeX{}, however, they are not accessible with a
4508 key binding any longer.
4511 @item @code{@@node} insertion
4512 The node insertion command, mapped to @kbd{C-c C-c n} in the native
4513 mode, is not mapped to any key in @AUCTeX{}. You can still access it
4514 through the Texinfo menu, though. Another alternative is to use the
4515 @kbd{C-c C-m} binding for macro insertion in @AUCTeX{}.
4517 @item Show the section structure
4518 The command @code{texinfo-show-structure} (@kbd{C-c C-s}) from the
4519 native mode does not have a key binding in @AUCTeX{}. The binding is
4520 used by @AUCTeX{} for sectioning.
4534 @unnumberedsec Key Index
4538 @node Function Index
4539 @unnumberedsec Function Index
4543 @node Variable Index
4544 @unnumberedsec Variable Index
4549 @unnumberedsec Concept Index