diff options
Diffstat (limited to 'elpa/auctex-13.1.3/doc/auctex.texi')
| -rw-r--r-- | elpa/auctex-13.1.3/doc/auctex.texi | 6200 |
1 files changed, 6200 insertions, 0 deletions
diff --git a/elpa/auctex-13.1.3/doc/auctex.texi b/elpa/auctex-13.1.3/doc/auctex.texi new file mode 100644 index 0000000..ca23668 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/auctex.texi @@ -0,0 +1,6200 @@ +\input texinfo +@comment %**start of header +@setfilename auctex.info +@include version.texi +@settitle AUCTeX @value{VERSION} +@c footnotestyle separate +@c paragraphindent 2 +@comment %**end of header +@include macros.texi +@copying +This manual is for @AUCTeX{} +(version @value{VERSION} from @value{UPDATED}), +a sophisticated @TeX{} environment for Emacs. + +Copyright @copyright{} 1992-1995, 2001, 2002, 2004-2022 +Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A +copy of the license is included in the section entitled ``GNU Free +Documentation License.'' +@end quotation +@end copying + +@dircategory Emacs +@direntry +* AUCTeX: (auctex). A sophisticated TeX environment for Emacs. +@end direntry +@dircategory TeX +@direntry +* AUCTeX: (auctex). A sophisticated TeX environment for Emacs. +@end direntry + +@iftex +@tolerance 10000 @emergencystretch 3em +@end iftex + +@finalout +@titlepage +@title @AUCTeX{} +@subtitle A sophisticated @TeX{} environment for Emacs +@subtitle Version @value{VERSION}, @value{UPDATED} +@author Kresten Krab Thorup +@author Per Abrahamsen +@author David Kastrup and others +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c Use @ifinfo _and_ @ifhtml here because Texinfo 3 cannot cope with +@c @ifnottex around a top node. +@ifinfo +@node top +@top @AUCTeX{} + +This manual may be copied under the conditions spelled out in +@ref{Copying this Manual}. + +@end ifinfo +@ifhtml +@node top +@top @AUCTeX{} +@insertcopying +@end ifhtml + +@contents + +@iftex +@unnumbered Executive Summary +@end iftex + +@AUCTeX{} is an integrated environment for editing @LaTeX{}, @ConTeXt{}, +doc@TeX{}, Texinfo, and @TeX{} files. + +Although @AUCTeX{} contains a large number of features, there are no +reasons to despair. You can continue to write @TeX{} and @LaTeX{} +documents the way you are used to, and only start using the multiple +features in small steps. @AUCTeX{} is not monolithic, each feature +described in this manual is useful by itself, but together they provide +an environment where you will make very few @LaTeX{} errors, and makes +it easy to find the errors that may slip through anyway. + +It is a good idea to make a printout of @AUCTeX{}'s reference card +@file{tex-ref.tex} or one of its typeset versions. + +If you want to make @AUCTeX{} aware of style files and multifile +documents right away, insert the following in your init file (usually +@file{~/.emacs.d/init.el}). + +@lisp +(setq TeX-auto-save t) +(setq TeX-parse-self t) +(setq-default TeX-master nil) +@end lisp + +Another thing you should enable is Ref@TeX{}, a comprehensive solution +for managing cross references, bibliographies, indices, document +navigation and a few other things. (@xref{Installation,,,reftex,The +Ref@TeX{} manual}.) + +For detailed information about the @previewlatex{} subsystem of +@AUCTeX{}, see @ref{Top,,Introduction,preview-latex,The @previewlatex{} +Manual}. + +There is a mailing list for general discussion about @AUCTeX{}: write a +mail with ``subscribe'' in the subject to +@email{auctex-request@@gnu.org} to join it. Send contributions to +@email{auctex@@gnu.org}. + +Bug reports should go to @email{bug-auctex@@gnu.org}, suggestions for +new features, and pleas for help should go to either +@email{auctex-devel@@gnu.org} (the @AUCTeX{} developers), or to +@email{auctex@@gnu.org} if they might have general interest. Please use +the command @kbd{M-x TeX-submit-bug-report @key{RET}} to report bugs if +possible. You can subscribe to a low-volume announcement list by +sending ``subscribe'' in the subject of a mail to +@email{info-auctex-request@@gnu.org}. + +@menu +* Copying:: Copying +* Introduction:: Introduction to @AUCTeX{} +* Editing:: Editing the Document Source +* Display:: Controlling Screen Display +* Processing:: Starting Processors, Viewers and Other Programs +* Customization:: Customization and Extension +* Appendices:: Copying, Changes, Development, FAQ, Texinfo mode +* Indices:: Indices + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Summary:: Overview of @AUCTeX{} +* Installation:: Installing @AUCTeX{} +* Quick Start:: Quick Start + +Editing the Document Source + +* Quotes:: Inserting double quotes +* Font Specifiers:: Inserting Font Specifiers +* Sectioning:: Inserting chapters, sections, etc. +* Environments:: Inserting Environment Templates +* Mathematics:: Entering Mathematics +* Completion:: Completion of macros +* Commenting:: Commenting text +* Indenting:: Reflecting syntactic constructs with whitespace +* Filling:: Automatic and manual line breaking + +Inserting Environment Templates + +* Equations:: Equations +* Floats:: Floats +* Itemize-like:: Itemize-like Environments +* Tabular-like:: Tabular-like Environments +* Customizing Environments:: Customizing Environments + +Controlling Screen Display + +* Font Locking:: Font Locking +* Folding:: Folding Macros and Environments +* Outline:: Outlining the Document +* Narrowing:: Restricting display and editing to a portion of the buffer +* Prettifying:: Displaying Greek and math macros as Unicode characters + +Font Locking + +* Fontification of macros:: Fontification of macros +* Fontification of quotes:: Fontification of quotes +* Fontification of math:: Fontification of math constructs +* Verbatim content:: Verbatim macros and environments +* Faces:: Faces used by font-latex +* Known problems:: Known fontification problems + +Starting Processors, Viewers and Other Programs + +* Commands:: Invoking external commands. +* Viewing:: Invoking external viewers. +* Debugging:: Debugging @TeX{} and @LaTeX{} output. +* Checking:: Checking the document. +* Control:: Controlling the processes. +* Cleaning:: Cleaning intermediate and output files. +* Documentation:: Documentation about macros and packages. + +Viewing the Formatted Output + +* Starting Viewers:: Starting viewers +* I/O Correlation:: Forward and inverse search + +Catching the errors + +* Ignoring warnings:: Controlling warnings to be reported +* Error overview:: List of all errors and warnings + +Customization and Extension + +* Multifile:: Multifile Documents +* Parsing Files:: Automatic Parsing of @TeX{} Files +* Internationalization:: Language Support +* Automatic:: Automatic Customization +* Style Files:: Writing Your Own Style Support + +Language Support + +* European:: Using @AUCTeX{} with European Languages +* Japanese:: Using @AUCTeX{} with Japanese + +Automatic Customization + +* Automatic Global:: Automatic Customization for the Site +* Automatic Private:: Automatic Customization for a User +* Automatic Local:: Automatic Customization for a Directory + +Writing Your Own Style Support + +* Simple Style:: A Simple Style File +* Adding Macros:: Adding Support for Macros +* Adding Environments:: Adding Support for Environments +* Adding Other:: Adding or Examining Other Information +* Hacking the Parser:: Automatic Extraction of New Things + +Copying, Changes, Development, FAQ + +* Copying this Manual:: +* Changes:: +* Development:: +* FAQ:: +* Texinfo mode:: + +Copying this Manual + +* GNU Free Documentation License:: License for copying this manual. + +Indices + +* Key Index:: +* Function Index:: +* Variable Index:: +* Concept Index:: + +@end detailmenu +@end menu + +@node Copying +@unnumbered Copying +@cindex Copying +@cindex Copyright +@cindex GPL +@cindex General Public License +@cindex License +@cindex Free +@cindex Free software +@cindex Distribution +@cindex Right +@cindex Warranty + +@c This text adapted from the Texinfo 2.16 distribution. + +@AUCTeX{} primarily consists of Lisp files for Emacs, but +there are also installation scripts and files and @TeX{} support files. +All of those are @dfn{free}; this means that everyone is free to use +them and free to redistribute them on a free basis. The files of +@AUCTeX{} are not in the public domain; they are copyrighted and there +are restrictions on their distribution, but these restrictions are +designed to permit everything that a good cooperating citizen would want +to do. What is not allowed is to try to prevent others from further +sharing any version of these programs that they might get from you. + +Specifically, we want to make sure that you have the right to give away +copies of the files that constitute @AUCTeX{}, that you receive source +code or else can get it if you want it, that you can change these files +or use pieces of them in new free programs, and that you know you can do +these things. + +To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute +copies of parts of @AUCTeX{}, you must give the recipients all the +rights that you have. You must make sure that they, too, receive or can +get the source code. And you must tell them their rights. + +Also, for our own protection, we must make certain that everyone finds +out that there is no warranty for @AUCTeX{}. If any parts are modified +by someone else and passed on, we want their recipients to know that +what they have is not what we distributed, so that any problems +introduced by others will not reflect on our reputation. + +The precise conditions of the licenses for the files currently being +distributed as part of @AUCTeX{} are found in the General Public +Licenses that accompany them. This manual specifically is covered by +the GNU Free Documentation License (@pxref{Copying this Manual}). + +@node Introduction +@chapter Introduction + +@menu +* Summary:: Overview of @AUCTeX{} +* Installation:: Installing @AUCTeX{} +* Quick Start:: Quick Start +@end menu + +@lowersections +@include intro.texi + +@include install.texi + +@include quickstart.texi +@raisesections + +@node Editing +@chapter Editing the Document Source + +The most commonly used commands/macros of @AUCTeX{} are those which +simply insert templates for often used @TeX{}, @LaTeX{}, or @ConTeXt{} +constructs, like font changes, handling of environments, etc. These +features are very simple, and easy to learn, and help you avoid mistakes +like mismatched braces, or @samp{\begin@{@}}-@samp{\end@{@}} pairs. + +Apart from that this chapter contains a description of some features for +entering more specialized sorts of text, for formatting the source by +indenting and filling and for navigating through the document. + +@menu +* Quotes:: Inserting quotes, dollars, and braces +* Font Specifiers:: Inserting Font Specifiers +* Sectioning:: Inserting chapters, sections, etc. +* Environments:: Inserting Environment Templates +* Mathematics:: Entering Mathematics +* Completion:: Completion of macros +* Marking:: Marking Environments, Sections, or Texinfo Nodes +* Commenting:: Commenting text +* Indenting:: Reflecting syntactic constructs with whitespace +* Filling:: Automatic and manual line breaking +@end menu + +@node Quotes +@section Insertion of Quotes, Dollars, and Braces + +@cindex Quotes +@cindex Double quotes +@cindex Braces +@cindex Brackets +@cindex Dollars +@cindex Math mode delimiters +@cindex Matching dollar signs +@cindex Display math mode + +@subheading Quotation Marks + +In @TeX{}, literal double quotes @samp{"like this"} are seldom used, +instead two single quotes are used @samp{``like this''}. To help you +insert these efficiently, @AUCTeX{} allows you to continue to press +@kbd{"} to insert two single quotes. To get a literal double quote, +press @kbd{"} twice. + +@deffn Command TeX-insert-quote @var{count} +@kindex " +(@kbd{"}) Insert the appropriate quote marks for @TeX{}. + +Inserts the value of @code{TeX-open-quote} (normally @samp{``}) or +@code{TeX-close-quote} (normally @samp{''}) depending on the context. +With prefix argument, always inserts @samp{"} characters. +@end deffn + +@defopt TeX-open-quote +String inserted by typing @kbd{"} to open a quotation. +(@xref{European}, for language-specific quotation mark insertion.) +@end defopt + +@defopt TeX-close-quote +String inserted by typing @kbd{"} to close a quotation. +(@xref{European}, for language-specific quotation mark insertion.) +@end defopt + +@defopt TeX-quote-after-quote +Determines the behavior of @kbd{"}. If it is non-nil, typing @kbd{"} +will insert a literal double quote. The respective values of +@code{TeX-open-quote} and @code{TeX-close-quote} will be inserted +after typing @kbd{"} once again. +@end defopt + +The @samp{babel} package provides special support for the requirements +of typesetting quotation marks in many different languages. If you use +this package, either directly or by loading a language-specific style +file, you should also use the special commands for quote insertion +instead of the standard quotes shown above. @AUCTeX{} is able to +recognize several of these languages and will change quote insertion +accordingly. @xref{European}, for details about this feature and how to +control it. + +@vindex LaTeX-csquotes-open-quote +@vindex LaTeX-csquotes-close-quote +@vindex LaTeX-csquotes-quote-after-quote +In case you are using the @samp{csquotes} package, you should customize +@code{LaTeX-csquotes-open-quote}, @code{LaTeX-csquotes-close-quote} and +@code{LaTeX-csquotes-quote-after-quote}. The quotation characters will +only be used if both variables---@code{LaTeX-csquotes-open-quote} and +@code{LaTeX-csquotes-close-quote}---are non-empty strings. But then the +@samp{csquotes}-related values will take precedence over the +language-specific ones. + +@subheading Dollar Signs + +In @AUCTeX{}, dollar signs should match like they do in @TeX{}. This +has been partially implemented, we assume dollar signs always match +within a paragraph. By default, the first @samp{$} you insert in a +paragraph will do nothing special. The second @samp{$} will match the +first. This will be indicated by moving the cursor temporarily over the +first dollar sign. + +@deffn Command TeX-insert-dollar @var{arg} +@kindex $ +(@kbd{$}) Insert dollar sign. + +Show matching dollar sign if this dollar sign end the @TeX{} math mode. + +With optional @var{arg}, insert that many dollar signs. +@end deffn + +@TeX{} and @LaTeX{} users often look for a way to insert inline +equations like @samp{$...$} or @samp{\(...\)} simply typing @kbd{$}. +@AUCTeX{} helps them through the customizable variable +@code{TeX-electric-math}. + +@defopt TeX-electric-math +If the variable is non-nil and you type @kbd{$} outside math mode, +@AUCTeX{} will automatically insert the opening and closing symbols for +an inline equation and put the point between them. The opening symbol +will blink when @code{blink-matching-paren} is non-nil. If +@code{TeX-electric-math} is nil, typing @kbd{$} simply inserts @samp{$} +at point, this is the default. + +Besides @code{nil}, possible values for this variable are @code{(cons +"$" "$")} for @TeX{} inline equations @samp{$...$}, and @code{(cons +"\\(" "\\)")} for @LaTeX{} inline equations @samp{\(...\)}. + +If the variable is non-nil and point is inside math mode right between a +couple of single dollars, pressing @kbd{$} will insert another pair of +dollar signs and leave the point between them. Thus, if +@code{TeX-electric-math} is set to @code{(cons "$" "$")} you can easily +obtain a @TeX{} display equation @samp{$$...$$} by pressing @kbd{$} +twice in a row. (Note that you should not use double dollar signs in +@LaTeX{} because this practice can lead to wrong spacing in typeset +documents.) + +In addition, when the variable is non-nil and there is an active region +outside math mode, typing @kbd{$} will put around the active region +symbols for opening and closing inline equation and keep the region +active, leaving point after the closing symbol. By pressing repeatedly +@kbd{$} while the region is active you can toggle between an inline +equation, a display equation, and no equation. To be precise, +@samp{$...$} is replaced by @samp{$$...$$}, whereas @samp{\(...\)} is +replaced by @samp{\[...\]}. +@end defopt + +If you want to automatically insert @samp{$...$} in plain @TeX{} files, +and @samp{\(...\)} in @LaTeX{} files by pressing @kbd{$}, add the +following to your init file +@lisp +(add-hook 'plain-TeX-mode-hook + (lambda () (set (make-local-variable 'TeX-electric-math) + (cons "$" "$")))) +(add-hook 'LaTeX-mode-hook + (lambda () (set (make-local-variable 'TeX-electric-math) + (cons "\\(" "\\)")))) +@end lisp + +Note that Texinfo mode does nothing special for @kbd{$}. It inserts +dollar sign(s) just in the same way as the other normal keys do. + +@subheading Braces + +To avoid unbalanced braces, it is useful to insert them pairwise. You +can do this by typing @kbd{C-c @{}. + +@deffn Command TeX-insert-braces +@kindex C-c @{ +(@kbd{C-c @{}) Make a pair of braces and position the cursor +to type inside of them. If there is an active region, put braces around +it and leave point after the closing brace. +@end deffn + +When writing complex math formulas in @LaTeX{} documents, you +sometimes need to adjust the size of braces with pairs of macros like +@samp{\left}-@samp{\right}, @samp{\bigl}-@samp{\bigr} and so on. You +can avoid unbalanced pairs with the help of @code{TeX-insert-macro}, +bound to @kbd{C-c C-m} or @kbd{C-c @key{RET}} (@pxref{Completion}). +If you insert left size adjusting macros such as @samp{\left}, +@samp{\bigl} etc.@: with @code{TeX-insert-macro}, it asks for left brace +to use and supplies automatically right size adjusting macros such as +@samp{\right}, @samp{\bigr} etc.@: and corresponding right brace in +addtion to the intended left macro and left brace. + +The completion by @code{TeX-insert-macro} also applies when entering +macros such as @samp{\langle}, @samp{\lfloor} and @samp{\lceil}, which +produce the left part of the paired braces. For example, inserting +@samp{\lfloor} by @kbd{C-c C-m} is immediately followed by the +insertion of @samp{\rfloor}. In addition, if the point was located +just after @samp{\left} or its friends, the corresponding +@samp{\right} etc.@: will be inserted in front of @samp{\rfloor}. +In both cases, active region is honored. + +As a side effect, when @code{LaTeX-math-mode} (@pxref{Mathematics}) is +on, just typing @kbd{`(} inserts not only @samp{\langle}, but also +@samp{\rangle}. + +If you do not like such auto completion at all, it can be disabled by a +user option. + +@defopt TeX-arg-right-insert-p +If this option is turned off, the automatic supply of the right macros +and braces is suppressed. +@end defopt + +@kindex ( +@kindex @{ +@kindex [ +When you edit @LaTeX{} documents, you can enable automatic brace +pairing when typing @kbd{(}, @kbd{@{} and @kbd{[}. + +@defopt LaTeX-electric-left-right-brace +If this option is on, just typing @kbd{(}, @kbd{@{} or @kbd{[} +immediately adds the corresponding right brace @samp{)}, @samp{@}} or +@samp{]}. The point is left after the opening brace. If there is an +active region, braces are put around it. + +They recognize the preceding backslash or size adjusting macros such +as @samp{\left}, @samp{\bigl} etc., so the following completions will +occur: +@itemize @bullet + +@item +(when typing single left brace) +@itemize @minus + +@item +@samp{(} -> @samp{()} + +@item +@samp{@{} -> @samp{@{@}} + +@item +@samp{[} -> @samp{[]} +@end itemize + +@item +(when typing left brace just after a backslash) +@itemize @minus + +@item +@samp{\(} -> @samp{\(\)} + +@item +@samp{\@{} -> @samp{\@{\@}} + +@item +@samp{\[} -> @samp{\[\]} +@end itemize + +@item +(when typing just after @samp{\left} or @samp{\bigl}) +@itemize @minus + +@item +@samp{\left(} -> @samp{\left(\right)} + +@item +@samp{\bigl[} -> @samp{\bigl[\bigr]} +@end itemize + +@item +(when typing just after @samp{\Bigl\}) +@itemize @minus + +@item +@samp{\Bigl\@{} -> @samp{\Bigl\@{\Bigr\@}} + +@end itemize + +@end itemize + +This auto completion feature may be a bit annoying when editing an +already existing @LaTeX{} document. In that case, use @kbd{C-u 1} or +@kbd{C-q} before typing @kbd{(}, @kbd{@{} or @kbd{[}. Then no +completion is done and just a single left brace is inserted. In fact, +with optional prefix @var{arg}, just that many open braces are +inserted without any completion. +@end defopt + +@node Font Specifiers +@section Inserting Font Specifiers + +@cindex Fonts +@cindex Font macros +@cindex Changing font +@cindex Specifying a font + +Perhaps the most used keyboard commands of @AUCTeX{} are the short-cuts +available for easy insertion of font changing macros. + +If you give an argument (that is, type @kbd{C-u}) to the font command, +the innermost font will be replaced, i.e.@: the font in the @TeX{} group +around point will be changed. The following table shows the available +commands, with @code{@point{}} indicating the position where the text +will be inserted. + +@table @kbd +@item C-c C-f C-b +@kindex C-c C-f C-b +@cindex @code{\textbf} +Insert @b{bold face} @samp{\textbf@{@point{}@}} text. + +@item C-c C-f C-m +@kindex C-c C-f C-m +@cindex @code{\textmd} +Insert @r{medium face} @samp{\textmd@{@point{}@}} text. + +@item C-c C-f C-i +@kindex C-c C-f C-i +@cindex @code{\textit} +Insert @i{italics} @samp{\textit@{@point{}@}} text. + +@item C-c C-f C-e +@kindex C-c C-f C-e +@cindex @code{\emph} +Insert @emph{emphasized} @samp{\emph@{@point{}@}} text. + +@item C-c C-f C-s +@kindex C-c C-f C-s +@cindex @code{\textsl} +Insert @slanted{slanted} @samp{\textsl@{@point{}@}} text. + +@item C-c C-f C-r +@kindex C-c C-f C-r +@cindex @code{\textrm} +Insert @r{roman} @samp{\textrm@{@point{}@}} text. + +@item C-c C-f C-f +@kindex C-c C-f C-f +@cindex @code{\textsf} +Insert @sansserif{sans serif} @samp{\textsf@{@point{}@}} text. + +@item C-c C-f C-t +@kindex C-c C-f C-t +@cindex @code{\texttt} +Insert @t{typewriter} @samp{\texttt@{@point{}@}} text. + +@item C-c C-f C-c +@kindex C-c C-f C-c +@cindex @code{\textsc} +Insert @sc{small caps} @samp{\textsc@{@point{}@}} text. + +@item C-c C-f C-l +@kindex C-c C-f C-l +@cindex @code{\textulc} +Insert upper lower case @samp{\textulc@{@point{}@}} text. + +@item C-c C-f C-w +@kindex C-c C-f C-w +@cindex @code{\textsw} +Insert @sc{swash} @samp{\textsw@{@point{}@}} text. + +@item C-c C-f C-n +@kindex C-c C-f C-n +@cindex @code{\textnormal} +Insert normal @samp{\textnormal@{@point{}@}} text. + +@item C-c C-f C-d +@kindex C-c C-f C-c +@cindex Deleting fonts +Delete the innermost font specification containing point. + +@end table + +@deffn Command TeX-font @var{replace} @var{what} +@kindex C-c C-f +(@kbd{C-c C-f}) Insert template for font change command. + +If @var{replace} is not nil, replace current font. @var{what} +determines the font to use, as specified by @code{TeX-font-list}. +@end deffn + +@defopt TeX-font-list +List of fonts used by @code{TeX-font}. + +Each entry is a list with three elements. The first element is the +key to activate the font. The second element is the string to insert +before point, and the third element is the string to insert after +point. An optional fourth element means always replace if not nil. +@end defopt + +@defopt LaTeX-font-list +List of fonts used by @code{TeX-font} in LaTeX mode. It has the same +structure as @code{TeX-font-list}. +@end defopt + +@node Sectioning +@section Inserting chapters, sections, etc. +@cindex Sectioning +@cindex Sections +@cindex Chapters +@cindex @code{\chapter} +@cindex @code{\section} +@cindex @code{\subsection} +@cindex @code{\label} + +Insertion of sectioning macros, that is @samp{\chapter}, +@samp{\section}, @samp{\subsection}, etc.@: and accompanying +@samp{\label}'s may be eased by using @kbd{C-c C-s}. This command is +highly customizable, the following describes the default behavior. + +When invoking you will be asked for a section macro to insert. An +appropriate default is automatically selected by @AUCTeX{}, that is +either: at the top of the document; the top level sectioning for that +document style, and any other place: The same as the last occurring +sectioning command. + +Next, you will be asked for the actual name of that section, and last +you will be asked for a label to be associated with that section. The +label will be prefixed by the value specified in +@code{LaTeX-section-hook}. + +@deffn Command LaTeX-section @var{arg} +@kindex C-c C-s +(@kbd{C-c C-s}) Insert a sectioning command. + +Determine the type of section to be inserted, by the argument +@var{arg}. + +@itemize @bullet +@item +If @var{arg} is nil or missing, use the current level. +@item +If @var{arg} is a list (selected by C-u), go downward one level. +@item +If @var{arg} is negative, go up that many levels. +@item +If @var{arg} is positive or zero, use absolute level: +@itemize + +@item +0 : part +@item +1 : chapter +@item +2 : section +@item +3 : subsection +@item +4 : subsubsection +@item +5 : paragraph +@item +6 : subparagraph +@end itemize +@end itemize + +The following variables can be set to customize the function. + +@vtable @code +@item LaTeX-section-hook +Hooks to be run when inserting a section. +@item LaTeX-section-label +Prefix to all section references. +@end vtable + +@end deffn + +The precise behavior of @code{LaTeX-section} is defined by the contents +of @code{LaTeX-section-hook}. + +@defopt LaTeX-section-hook +List of hooks to run when a new section is inserted. + +The following variables are set before the hooks are run + +@vtable @code +@item LaTeX-level +Numeric section level, default set by prefix arg to +@code{LaTeX-section}. +@item LaTeX-name +Name of the sectioning command, derived from @code{LaTeX-level}. +@item LaTeX-title +The title of the section, default to an empty string. +@item LaTeX-toc +Entry for the table of contents list, default nil. +@item LaTeX-done-mark +Position of point afterwards, default nil meaning after the inserted +text. +@end vtable + +A number of hooks are already defined. Most likely, you will be able to +get the desired functionality by choosing from these hooks. + +@ftable @code +@item LaTeX-section-heading +Query the user about the name of the sectioning command. Modifies +@code{LaTeX-level} and @code{LaTeX-name}. +@item LaTeX-section-title +Query the user about the title of the section. Modifies @code{LaTeX-title}. +@item LaTeX-section-toc +Query the user for the toc entry. Modifies @code{LaTeX-toc}. +@item LaTeX-section-section +Insert @LaTeX{} section command according to @code{LaTeX-name}, +@code{LaTeX-title}, and @code{LaTeX-toc}. If @code{LaTeX-toc} is nil, no +toc entry is inserted. If @code{LaTeX-toc} or @code{LaTeX-title} are +empty strings, @code{LaTeX-done-mark} will be placed at the point they +should be inserted. +@item LaTeX-section-label +Insert a label after the section command. Controlled by the variable +@code{LaTeX-section-label}. +@end ftable + +To get a full featured @code{LaTeX-section} command, insert + +@lisp +(setq LaTeX-section-hook + '(LaTeX-section-heading + LaTeX-section-title + LaTeX-section-toc + LaTeX-section-section + LaTeX-section-label)) +@end lisp + +in your init file such as @file{init.el} or @file{.emacs}. +@end defopt + +The behavior of @code{LaTeX-section-label} is determined by the +variable @code{LaTeX-section-label}. + +@defopt LaTeX-section-label +Default prefix when asking for a label. + +If it is a string, it is used unchanged for all kinds of sections. +If it is nil, no label is inserted. +If it is a list, the list is searched for a member whose car is equal +to the name of the sectioning command being inserted. The cdr is then +used as the prefix. If the name is not found, or if the cdr is nil, +no label is inserted. + +@cindex Prefix for labels +@cindex Label prefix +@cindex Labels +By default, chapters have a prefix of @samp{cha:} while sections and +subsections have a prefix of @samp{sec:}. Labels are not automatically +inserted for other types of sections. +@end defopt + +@node Environments +@section Inserting Environment Templates +@cindex Environments +@cindex @samp{\begin} +@cindex @samp{\end} + +A large apparatus is available that supports insertions of environments, +that is @samp{\begin@{@}} --- @samp{\end@{@}} pairs. + +@AUCTeX{} is aware of most of the actual environments available in a +specific document. This is achieved by examining your +@samp{\documentclass} command, and consulting a precompiled list of +environments available in a large number of styles. + +Most of these are described further in the following sections, and you +may easily specify more. @xref{Customizing Environments}. + +You insert an environment with @kbd{C-c C-e}, and select an environment +type. Depending on the environment, @AUCTeX{} may ask more questions +about the optional parts of the selected environment type. With +@kbd{C-u C-c C-e} you will change the current environment. + +@deffn Command LaTeX-environment @var{arg} +@kindex C-c C-e +(@kbd{C-c C-e}) @AUCTeX{} will prompt you for an environment +to insert. At this prompt, you may press @key{TAB} or @key{SPC} to +complete a partially written name, and/or to get a list of available +environments. After selection of a specific environment @AUCTeX{} may +prompt you for further specifications. + +If the optional argument @var{arg} is non-nil (i.e.@: you have given a +prefix argument), the current environment is modified and no new +environment is inserted. +@end deffn + +@AUCTeX{} helps you adding labels to environments which use them, such +as @samp{equation}, @samp{figure}, @samp{table}, etc@dots{} When you +insert one of the supported environments with @kbd{C-c C-e}, you will be +automatically prompted for a label. You can select the prefix to be +used for such environments with the @code{LaTeX-label-alist} variable. +@defopt LaTeX-label-alist +List the prefixes to be used for the label of each supported +environment. + +This is an alist whose car is the environment name, and the cdr either +the prefix or a symbol referring to one. + +If the name is not found, or if the cdr is nil, no label is +automatically inserted for that environment. + +If you want to automatically insert a label for a environment but with +an empty prefix, use the empty string @code{""} as the cdr of the +corresponding entry. +@end defopt + +As a default selection, @AUCTeX{} will suggest the environment last +inserted or, as the first choice the value of the variable +@code{LaTeX-default-environment}. + +@defopt LaTeX-default-environment +Default environment to insert when invoking @code{LaTeX-environment} +first time. When the current environment is @samp{document}, it is +overriden by @code{LaTeX-default-document-environment}. +@end defopt + +@defvar LaTeX-default-document-environment +Default environment when invoking @samp{LaTeX-environment} and the +current environment is @samp{document}. It is intended to be used in +@LaTeX{} class style files. For example, in @file{beamer.el} it is set +to @code{frame}, in @file{letter.el} to @code{letter}, and in +@file{slides.el} to @code{slide}. +@end defvar + +If the document is empty, or the cursor is placed at the top of the +document, @AUCTeX{} will default to insert a @samp{document} environment +prompting also for the insertion of @samp{\documentclass} and +@samp{\usepackage} macros. You will be prompted for a new package until +you enter nothing. If you do not want to insert any @samp{\usepackage} +at all, just press @key{RET} at the first @samp{Packages} prompt. + +@AUCTeX{} distinguishes normal and expert environments. By default, it +will offer completion only for normal environments. This behavior is +controlled by the user option @code{TeX-complete-expert-commands}. + +@defopt TeX-complete-expert-commands +Complete macros and environments marked as expert commands. + +Possible values are nil, t, or a list of style names. + +@table @asis +@item nil +Don't complete expert commands (default). +@item t +Always complete expert commands. +@item (@var{styles} @dots{}) +Only complete expert commands of @var{styles}. +@end table +@end defopt + + +@menu +* Equations:: Equations +* Floats:: Floats +* Itemize-like:: Itemize-like Environments +* Tabular-like:: Tabular-like Environments +* Customizing Environments:: Customizing Environments +@end menu + +You can close the current environment with @kbd{C-c ]}, but we suggest +that you use @kbd{C-c C-e} to insert complete environments instead. + +@deffn Command LaTeX-close-environment +@kindex C-c ] +(@kbd{C-c ]}) Insert an @samp{\end} that matches the current environment. +@end deffn + +@AUCTeX{} offers keyboard shortcuts for moving point to the beginning +and to the end of the current environment. +@deffn Command LaTeX-find-matching-begin +@kindex C-M-a +(@kbd{C-M-a}) Move point to the @samp{\begin} of the current +environment. + +If this command is called inside a comment and +@code{LaTeX-syntactic-comments} is enabled, try to find the environment +in commented regions with the same comment prefix. +@end deffn + +@deffn Command LaTeX-find-matching-end +@kindex C-M-e +(@kbd{C-M-e}) Move point to the @samp{\end} of the current environment. + +If this command is called inside a comment and +@code{LaTeX-syntactic-comments} is enabled, try to find the environment +in commented regions with the same comment prefix. +@end deffn + +@node Equations +@subsection Equations +@cindex Equations +@cindex Equation +@cindex Eqnarray +@cindex amsmath + +When inserting equation-like environments, the @samp{\label} will have a +default prefix, which is controlled by the following variables: + +@defopt LaTeX-equation-label +Prefix to use for `equation' labels. +@end defopt + +@defopt LaTeX-eqnarray-label +Prefix to use for `eqnarray' labels. +@end defopt + +@defopt LaTeX-amsmath-label +Prefix to use for amsmath equation labels. Amsmath equations include +@samp{align}, @samp{alignat}, @samp{xalignat}, @samp{multline}, +@samp{flalign} and @samp{gather}. +@end defopt + +@node Floats +@subsection Floats +@cindex Floats +@cindex Figures +@cindex Figure environment +@cindex Tables +@cindex Table environment + +Figures and tables (i.e., floats) may also be inserted using @AUCTeX{}. +After choosing either `figure' or `table' in the environment list +described above, you will be prompted for a number of additional things. + +@table @var +@item float position +This is the optional argument of float environments that controls how +they are placed in the final document. In @LaTeX{} this is a sequence +of the letters @samp{htbp} as described in the @LaTeX{} manual. The +value will default to the value of @code{LaTeX-float}. +@vindex LaTeX-float + +@item caption +This is the caption of the float. The default is to insert the caption +at the bottom of the float. You can specify floats where the caption +should be placed at the top with @code{LaTeX-top-caption-list}. +@vindex LaTeX-top-caption-list + +@item short caption +If the specified caption is greater than a specific length, then a short +caption is prompted for and it is inserted as an optional argument to +the @samp{\caption} macro. The length that a caption needs to be before +prompting for a short version is controlled by +@code{LaTeX-short-caption-prompt-length}. +@vindex LaTeX-short-caption-prompt-length + +@item label +The label of this float. The label will have a default prefix, which is +controlled by the variables @code{LaTeX-figure-label} and +@code{LaTeX-table-label}. +@vindex LaTeX-figure-label +@vindex LaTeX-table-label +@cindex Prefix for labels +@cindex Label prefix +@cindex Labels +@end table + +Moreover, you will be asked if you want the contents of the float +environment to be horizontally centered. Upon a positive answer a +@samp{\centering} macro will be inserted at the beginning of the float +environment. + +@defopt LaTeX-float +Default placement for floats. +@end defopt + +@defopt LaTeX-figure-label +Prefix to use for figure labels. +@end defopt + +@defopt LaTeX-table-label +Prefix to use for table labels. +@end defopt + +@defopt LaTeX-top-caption-list +List of float environments with top caption. +@end defopt + +@defopt LaTeX-short-caption-prompt-length +Number of chars a caption should be before prompting for a short +caption. +@end defopt + +@node Itemize-like +@subsection Itemize-like Environments +@cindex Itemize +@cindex Enumerates +@cindex Descriptions +@cindex Items +@cindex \item + +In an itemize-like environment, nodes (i.e., @samp{\item}s) may be +inserted using @kbd{C-c @key{LFD}}. + +@deffn Command LaTeX-insert-item +@kindex C-c @key{LFD} +(@kbd{C-c @key{LFD}}) Close the current item, move to the next line and +insert an appropriate @samp{\item} for the current environment. That is, +`itemize' and `enumerate' will have @samp{\item } inserted, while +`description' will have @samp{\item[] } inserted. +@end deffn + +@defopt TeX-arg-item-label-p +If non-nil, you will always be asked for optional label in items. +Otherwise, you will be asked only in description environments. +@end defopt + +@node Tabular-like +@subsection Tabular-like Environments +@cindex amsmath + +When inserting Tabular-like environments, that is, `tabular' `array' +etc., you will be prompted for a template for that environment. +Related variables: + +@defopt LaTeX-default-format +Default format string for array and tabular environments. +@end defopt + +@defopt LaTeX-default-width +Default width for minipage and tabular* environments. +@end defopt + +@defopt LaTeX-default-position +Default position string for array and tabular environments. If nil, +act like the empty string is given, but don't prompt for a position. +@end defopt + +@AUCTeX{} calculates the number of columns from the format string and +inserts the suitable number of ampersands. + +You can use @kbd{C-c @key{LFD}} (@code{LaTeX-insert-item}) to terminate +rows in these environments. It supplies line break macro @samp{\\} and +inserts the suitable number of ampersands on the next line. @AUCTeX{} +also supports the @samp{*@{num@}@{cols@}} notation (which may contain +another @samp{*}-expression) in the format string when calculating the +number of ampersands. Please note that @samp{num} and @samp{cols} must +be enclosed in braces; expressions like @samp{*2l} are not recognized +correctly by the algorithm. + +@deffn Command LaTeX-insert-item +@kindex C-c @key{LFD} +(@kbd{C-c @key{LFD}}) Close the current row with @samp{\\}, move to the +next line and insert an appropriate number of ampersands for the current +environment. +@end deffn + +Similar supports are provided for various amsmath environments such as +@samp{align}, @samp{gather}, @samp{alignat}, @samp{matrix} etc. Try +typing @kbd{C-c @key{LFD}} in these environments. It recognizes the +current environment and does the appropriate job depending on the +context. + +@node Customizing Environments +@subsection Customizing Environments + +@xref{Adding Environments}, for how to customize the list of known +environments. + +@node Mathematics +@section Entering Mathematics +@cindex Mathematics +@cindex Symbols +@cindex Abbreviations +@vindex LaTeX-math-default + +@TeX{} is written by a mathematician, and has always contained good +support for formatting mathematical text. @AUCTeX{} supports this +tradition, by offering a special minor mode for entering text with many +mathematical symbols. You can enter this mode by typing @kbd{C-c +~}. + +@deffn Command LaTeX-math-mode +@kindex C-c ~ +(@kbd{C-c ~}) Toggle @LaTeX{} Math mode. This is a minor mode rebinding +the key @code{LaTeX-math-abbrev-prefix} to allow easy typing of +mathematical symbols. @kbd{`} will read a character from the keyboard, +and insert the symbol as specified in @code{LaTeX-math-default} and +@code{LaTeX-math-list}. If given a prefix argument, the symbol will be +surrounded by dollar signs. +@end deffn + +You can use another prefix key (instead of @kbd{`}) by setting the +variable @code{LaTeX-math-abbrev-prefix}. + +To enable @LaTeX{} Math mode by default, add the following in your +init file such as @file{init.el} or @file{.emacs}: +@lisp +(add-hook 'LaTeX-mode-hook #'LaTeX-math-mode) +@end lisp + +@defopt LaTeX-math-abbrev-prefix +A string containing the prefix of @code{LaTeX-math-mode} commands; This +value defaults to @kbd{`}. + +The string has to be a key or key sequence in a format understood by the +@code{kbd} macro. This corresponds to the syntax usually used in the +manuals for Emacs Lisp. +@end defopt + +The variable @code{LaTeX-math-list} allows you to add your own mappings. + +@defopt LaTeX-math-list +A list containing user-defined keys and commands to be used in @LaTeX{} +Math mode. Each entry should be a list of two to four elements. + +First, the key to be used after @code{LaTeX-math-abbrev-prefix} for macro +insertion. The key can be a character (e.g.@: @samp{?o}) for a single +stroke or a string (e.g.@: @samp{"o a"}) for a multi-stroke binding. If it +is nil, the symbol has no associated keystroke (it is available in the +menu, though). + +Second, a string representing the name of the macro (without a leading +backslash.) + +Third, a string representing the name of a submenu the command should be +added to. Use a list of strings in case of nested menus. + +Fourth, the position of a Unicode character to be displayed in the menu +alongside the macro name. This is an integer value. +@end defopt + +@defopt LaTeX-math-menu-unicode +Whether the @LaTeX{} Math menu should try using Unicode for effect. Your Emacs +built must be able to display include Unicode characters in menus for +this feature. +@end defopt + +@AUCTeX{}'s reference card @file{tex-ref.tex} includes a list of all +math mode commands. + +@cindex subscript +@cindex superscript +@kindex _ +@kindex ^ +@AUCTeX{} can help you write subscripts and superscripts in math +constructs by automatically inserting a pair of braces after typing +@key{_} or @key{^} respectively and putting point between the braces. +In order to enable this feature, set the variable +@code{TeX-electric-sub-and-superscript} to a non-nil value. + +@defopt TeX-electric-sub-and-superscript +If non-nil, insert braces after typing @key{^} and @key{_} in math mode. +@end defopt + +@cindex input method +You can automatically turn off input methods, used to input non-ascii +characters, when you begin to enter math constructs. + +@defopt TeX-math-input-method-off-regexp +Input method matching this regular expression is turned off when @kbd{$} +is typed to begin math mode or a math environment is inserted by +@kbd{C-c C-e} (@code{LaTeX-environment}). +@end defopt + +@node Completion +@section Completion +@cindex Completion +@cindex Expansion +@cindex Macro expansion +@cindex Macro completion +@cindex Macro arguments +@cindex Arguments to @TeX{} macros + +Emacs lisp programmers probably know the @code{lisp-complete-symbol} +command which was bound to @kbd{M-@key{TAB}} until completion-at-point +became the new standard completion facility (see below). Users of the +wonderful ispell mode know and love the @code{ispell-complete-word} +command from that package. Similarly, @AUCTeX{} has a +@code{TeX-complete-symbol} command, by default bound to +@kbd{M-@key{TAB}} which is equivalent to @kbd{C-M-i}. Using +@code{TeX-complete-symbol} makes it easier to type and remember the +names of long @LaTeX{} macros. + +In order to use @code{TeX-complete-symbol}, you should write a backslash +and the start of the macro. Typing @kbd{M-@key{TAB}} will now complete +as much of the macro, as it unambiguously can. For example, if you type +`@samp{\renewc}' and then @kbd{M-@key{TAB}}, it will expand to +`@samp{\renewcommand}'. But there's more: if point is just after +@samp{\begin@{}, then @code{TeX-complete-symbol} will complete @LaTeX{} +environments, etc. This is controlled by @code{TeX-complete-list}. + +@deffn Command TeX-complete-symbol +@kindex M-@key{TAB} +(@kbd{M-@key{TAB}}) Complete @TeX{} symbol before point. +@end deffn + +@defvar TeX-complete-list +List of ways to complete the preceding text. + +Each entry is a list with the following elements: + +@enumerate +@item +Regexp matching the preceding text or a predicate of arity 0 which +returns non-nil and sets `match-data' appropriately if it is applicable. +@item +A number indicating the subgroup in the regexp containing the text. +@item +A function returning an alist of possible completions. +@item +Text to append after a succesful completion. +@end enumerate + +Or alternatively: + +@enumerate +@item +Regexp matching the preceding text. +@item +Function to do the actual completion. +@end enumerate +@end defvar + +More recent Emacs versions have a new completion mechanism. Modes may +define and register custom @code{completion-at-point} functions and when the +user invokes @code{completion-at-point} (usually bound to +@kbd{M-@key{TAB}}), all such registered functions are consulted for +checking for possible completions. Modern completion UIs like +@i{company-mode} support this completion-at-point facility. + +@defun TeX--completion-at-point +@AUCTeX{}'s completion-at-point function which is automatically added to +@code{completion-at-point-functions} in @TeX{} and @LaTeX{} buffers. + +It offers the same completion candidates as would +@code{TeX-complete-symbol} (and is also controlled by +@code{TeX-complete-list}) except that it doesn't fall back on +@code{ispell-complete-word} which would be awkward with completion UIs +like @i{company-mode}. +@end defun + +A more direct way to insert a macro is with @code{TeX-insert-macro}, +bound to @kbd{C-c C-m} which is equivalent to @kbd{C-c @key{RET}}. It +has the advantage over completion that it knows about the argument of +most standard @LaTeX{} macros, and will prompt for them. It also knows +about the type of the arguments, so it will for example give completion +for the argument to @samp{\include}. Some examples are listed below. + +@deffn Command TeX-insert-macro +@kindex C-c C-m +(@kbd{C-c C-m} or @kbd{C-c @key{RET}}) Prompt (with completion) for the +name of a @TeX{} macro, and if @AUCTeX{} knows the macro, prompt for +each argument. +@end deffn + +As a default selection, @AUCTeX{} will suggest the macro last inserted +or, as the first choice the value of the variable +@code{TeX-default-macro}. + +@defopt TeX-default-macro +Default macro to insert when invoking @code{TeX-insert-macro} first time. +@end defopt + +@defopt TeX-insert-macro-default-style +Specifies whether @code{TeX-insert-macro} will ask for all optional +arguments. + +If set to the symbol @code{show-optional-args}, @code{TeX-insert-macro} +asks for optional arguments of @TeX{} marcos, unless the previous +optional argument has been rejected. If set to +@code{show-all-optional-args}, @code{TeX-insert-macro} asks for all +optional arguments. @code{mandatory-args-only}, @code{TeX-insert-macro} +asks only for mandatory arguments. When @code{TeX-insert-macro} is +called with prefix argument (@kbd{C-u}), it's the other way round. +@c FIXME: Now that the option has 3 candidates, it isn't clear what "the +@c other way round" means. + +Note that for some macros, there are special mechanisms, e.g.@: +@code{TeX-arg-cite-note-p} and @code{LaTeX-includegraphics-options-alist}. +@end defopt + + +A faster alternative is to enable the option +@code{TeX-electric-escape}. + +@defopt TeX-electric-escape +If this is non-nil, typing the @TeX{} escape character @kbd{\} will +invoke the command @code{TeX-electric-macro}. + +In Texinfo mode, the command is invoked by @kbd{@@} instead. +@end defopt + +The difference between @code{TeX-insert-macro} and +@code{TeX-electric-macro} is that space key @key{SPC} will complete and exit from the +minibuffer in @code{TeX-electric-macro}. Use @key{TAB} if you merely +want to complete. + +@deffn Command TeX-electric-macro +Prompt (with completion) for the name of a @TeX{} macro, +and if @AUCTeX{} knows the macro, prompt for each argument. +Space (@key{SPC}) will complete and exit. +@end deffn + +By default @AUCTeX{} will put an empty set braces @samp{@{@}} after a +macro with no arguments to stop it from eating the next whitespace. +This is suppressed inside math mode and can be disabled totally by +setting @code{TeX-insert-braces} to nil. + +@defopt TeX-insert-braces +If non-nil, append a empty pair of braces after inserting a macro with +no arguments. +@end defopt + +@defopt TeX-insert-braces-alist +Control the insertion of a pair of braces after a macro on a per macro +basis. + +This variable is an alist. Each element is a cons cell, whose car is +the macro name, and the cdr is non-nil or nil, depending on whether a +pair of braces should be, respectively, appended or not to the macro. + +If a macro has an element in this variable, @AUCTeX{} will +use its value to decide what to do, whatever the value of the variable +@code{TeX-insert-braces}. +@end defopt + +Completions work because @AUCTeX{} can analyze @TeX{} files, and store +symbols in Emacs Lisp files for later retrieval. @xref{Automatic}, for +more information. + +@AUCTeX{} distinguishes normal and expert macros. By default, it will +offer completion only for normal commands. This behavior can be +controlled using the user option @code{TeX-complete-expert-commands}. + +@defopt TeX-complete-expert-commands +Complete macros and environments marked as expert commands. + +Possible values are nil, t, or a list of style names. + +@table @asis +@item nil +Don't complete expert commands (default). +@item t +Always complete expert commands. +@item (@var{styles} @dots{}) +Only complete expert commands of @var{styles}. +@end table +@end defopt + + +@cindex \cite, completion of +@cindex Bib@TeX{}, completion +@cindex cite, completion of +@cindex bibliography, completion +@cindex citations, completion of +@cindex \label, completion +@cindex \ref, completion +@cindex labels, completion of +@AUCTeX{} will also make completion for many macro arguments, for +example existing labels when you enter a @samp{\ref} macro with +@code{TeX-insert-macro} or @code{TeX-electric-macro}, and Bib@TeX{} +entries when you enter a @samp{\cite} macro. For this kind of +completion to work, parsing must be enabled as described in +@ref{Parsing Files}. For @samp{\cite} you must also make sure that +the Bib@TeX{} files have been saved at least once after you enabled +automatic parsing on save, and that the basename of the Bib@TeX{} file +does not conflict with the basename of one of @TeX{} files. + +@node Marking +@section Marking Environments, Sections, or Texinfo Nodes + +You can mark the current environment by typing @kbd{C-c .}, or the +current section by typing @kbd{C-c *}. + +In Texinfo documents you can type @kbd{C-M-h} to mark the current node. + +When the region is set, the point is moved to its beginning and the mark +to its end. + +@menu +* Marking (LaTeX):: @LaTeX{} Commands for Marking Environments and Sections +* Marking (Texinfo):: Texinfo Commands for Marking Environments, Sections, and Nodes +@end menu + +@node Marking (LaTeX) +@subsection @LaTeX{} Commands for Marking Environments and Sections + +@deffn Command LaTeX-mark-section +@kindex C-c * +(@kbd{C-c *}) Set mark at end of current logical section, and point at +top. + +With a non-nil prefix argument, mark only the region from the current +section start to the next sectioning command. Thereby subsections are +not being marked. Otherwise, any included subsections are also marked +along with current section. +@end deffn + +@deffn Command LaTeX-mark-environment +@kindex C-c . +(@kbd{C-c .}) Set mark to the end of the current environment and point +to the matching beginning. + +If a prefix argument is given, mark the respective number of enclosing +environments. The command will not work properly if there are +unbalanced begin-end pairs in comments and verbatim environments. +@end deffn + +@node Marking (Texinfo) +@subsection Texinfo Commands for Marking Environments and Sections + +@deffn Command Texinfo-mark-section +@kindex C-c * +(@kbd{C-c *}) Mark the current section, with inclusion of any containing +node. + +@vindex outline-regexp +@vindex texinfo-section-list +The current section is detected as starting by any of the structuring +commands matched by the regular expression in the variable +@code{outline-regexp} which in turn is a regular expression matching any +element of the variable @code{texinfo-section-list}. + +With a non-nil prefix argument, mark only the region from the current +section start to the next sectioning command. Thereby subsections are +not being marked. Otherwise, any included subsections are also marked. + +Note that when the current section is starting immediately after a node +command, then the node command is also marked as part of the section. +@end deffn + +@deffn Command Texinfo-mark-environment +@kindex C-c . +(@kbd{C-c .}) Set mark to the end of the current environment and point +to the matching beginning. + +If a prefix argument is given, mark the respective number of enclosing +environments. The command will not work properly if there are +unbalanced begin-end pairs in comments and verbatim environments. +@end deffn + +@deffn Command Texinfo-mark-node +@kindex C-M-h +(@kbd{C-M-h}) Mark the current node. This is the node in which point is +located. It is starting at the previous occurrence of the keyword +@code{@@node} and ending at next occurrence of the keywords +@code{@@node} or @code{@@bye}. +@end deffn + +@node Commenting +@section Commenting + +It is often necessary to comment out temporarily a region of @TeX{} or +@LaTeX{} code. This can be done with the commands @kbd{C-c ;} and +@kbd{C-c %}. @kbd{C-c ;} will comment out all lines in the current +region, while @kbd{C-c %} will comment out the current paragraph. +Type @kbd{C-c ;} again to uncomment all lines of a commented region, +or @kbd{C-c %} again to uncomment all comment lines around point. +These commands will insert or remove a single @samp{%} respectively. + +@deffn Command TeX-comment-or-uncomment-region +@kindex C-c ; +(@kbd{C-c ;}) Add or remove @samp{%} from the beginning of each line +in the current region. Uncommenting works only if the region encloses +solely commented lines. If @AUCTeX{} should not try to guess if the +region should be commented or uncommented the commands +@code{TeX-comment-region} and @code{TeX-uncomment-region} can be used +to explicitly comment or uncomment the region in concern. +@end deffn + +@deffn Command TeX-comment-or-uncomment-paragraph +@kindex C-c % +(@kbd{C-c %}) Add or remove @samp{%} from the beginning of each line +in the current paragraph. When removing @samp{%} characters the +paragraph is considered to consist of all preceding and succeeding +lines starting with a @samp{%}, until the first non-comment line. +@end deffn + +@node Indenting +@section Indenting +@cindex Formatting +@cindex Indenting +@cindex Indentation +@cindex Reformatting +@cindex Reindenting + +Indentation means the addition of whitespace at the beginning of lines +to reflect special syntactical constructs. This makes it easier to see +the structure of the document, and to catch errors such as a missing +closing brace. Thus, the indentation is done for precisely the same +reasons that you would indent ordinary computer programs. + +Indentation is done by @LaTeX{} environments and by @TeX{} groups, that +is the body of an environment is indented by the value of +@code{LaTeX-indent-level} (default 2). Also, items of an `itemize-like' +environment are indented by the value of @code{LaTeX-item-indent}, +default @minus{}2. (Items are identified with the help of +@code{LaTeX-item-regexp}.) If more environments are nested, they are +indented `accumulated' just like most programming languages usually are +seen indented in nested constructs. +@vindex LaTeX-indent-level +@vindex LaTeX-item-indent +@vindex LaTeX-item-regexp + +You can explicitly indent single lines, usually by pressing @key{TAB}, +or marked regions by calling @code{indent-region} on it. If you have +@code{auto-fill-mode} enabled and a line is broken while you type it, +Emacs automatically cares about the indentation in the following line. +If you want to have a similar behavior upon typing @key{RET}, you can +customize the variable @code{TeX-newline-function} and change the +default of @code{newline} which does no indentation to +@code{newline-and-indent} which indents the new line or +@code{reindent-then-newline-and-indent} which indents both the current +and the new line. +@vindex TeX-newline-function +@findex indent-region +@cindex auto-fill-mode + +There are certain @LaTeX{} environments which should be indented in a +special way, like @samp{tabular} or @samp{verbatim}. Those environments +may be specified in the variable @code{LaTeX-indent-environment-list} +together with their special indentation functions. Taking the +@samp{verbatim} environment as an example you can see that +@code{current-indentation} is used as the indentation function. This +will stop @AUCTeX{} from doing any indentation in the environment if you +hit @key{TAB} for example. +@vindex LaTeX-indent-environment-list + +There are environments in @code{LaTeX-indent-environment-list} which do +not bring a special indentation function with them. This is due to the +fact that first the respective functions are not implemented yet and +second that filling will be disabled for the specified environments. +This shall prevent the source code from being messed up by accidently +filling those environments with the standard filling routine. If you +think that providing special filling routines for such environments +would be an appropriate and challenging task for you, you are invited to +contribute. (@xref{Filling}, for further information about the filling +functionality.) +@vindex LaTeX-indent-environment-list + +The check for the indentation function may be enabled or disabled by +customizing the variable @code{LaTeX-indent-environment-check}. +@vindex LaTeX-indent-environment-check + +For tabular-like environments, @AUCTeX{} has a built-in function to indent +according to preceding @samp{&} signs and assigns it to all known +tabular-like environments in the default value of +@code{LaTeX-indent-environment-list}. + +@cindex align.el +@findex align-current +As a side note with regard to formatting special environments: Newer +Emacsen include @file{align.el} and therefore provide some support for +formatting @samp{tabular} and @samp{tabbing} environments with the +function @code{align-current} which will nicely align columns in the +source code. + +@AUCTeX{} is able to format commented parts of your code just as any +other part. This means @LaTeX{} environments and @TeX{} groups in +comments will be indented syntactically correct if the variable +@code{LaTeX-syntactic-comments} is set to t. If you disable it, +comments will be filled like normal text and no syntactic indentation +will be done. +@vindex LaTeX-syntactic-comments + +Following you will find a list of most commands and variables related +to indenting with a small summary in each case: + +@table @kbd +@item @key{TAB} +@kindex @key{TAB} +@findex LaTeX-indent-line +@code{LaTeX-indent-line} will indent the current line. + +@item @key{LFD} +@itemx C-j +@kindex @key{LFD} +@kindex C-j +@code{newline-and-indent} inserts a new line (much like @key{RET}) and +moves the cursor to an appropriate position by the left margin. + +Most keyboards nowadays lack a linefeed key and @kbd{C-j} may be tedious +to type. Therefore you can customize @AUCTeX{} to perform indentation +upon typing @key{RET} as well. The respective option is called +@code{TeX-newline-function}. +@end table + +@defopt LaTeX-indent-environment-list +List of environments with special indentation. The second element in +each entry is the function to calculate the indentation level in +columns. +@end defopt + +@defopt LaTeX-indent-level +Number of spaces to add to the indentation for each @samp{\begin} not +matched by a @samp{\end}. +@end defopt + +@defopt LaTeX-item-indent +Number of spaces to add to the indentation for @samp{\item}'s in list +environments. +@end defopt + +@defopt TeX-brace-indent-level +Number of spaces to add to the indentation for each @samp{@{} not +matched by a @samp{@}}. +@end defopt + +@defopt LaTeX-syntactic-comments +If non-nil comments will be filled and indented according to @LaTeX{} +syntax. Otherwise they will be filled like normal text. +@end defopt + +@defopt TeX-newline-function +Used to specify the function which is called when @key{RET} is pressed. +This will normally be @code{newline} which simply inserts a new line. +In case you want to have @AUCTeX{} do indentation as well when you press +@key{RET}, use the built-in functions @code{newline-and-indent} or +@code{reindent-then-newline-and-indent}. The former inserts a new line +and indents the following line, i.e.@: it moves the cursor to the right +position and therefore acts as if you pressed @key{LFD}. The latter +function additionally indents the current line. If you choose +@samp{Other}, you can specify your own fancy function to be called when +@key{RET} is pressed. +@end defopt + +@vindex LaTeX-begin-regexp +@vindex LaTeX-end-regexp +@AUCTeX{} treats by default @samp{\[...\]} math mode as a regular +environment and indents it accordingly. If you do not like such +behavior you only need to remove @code{\|\[} and @code{\|\]} from +@code{LaTeX-begin-regexp} and @code{LaTeX-end-regexp} variables +respectively. + +A closely related topic is indenting of text enclosed in square brackets, +parentheses and other pairs. @AUCTeX{} offers two variables which control +if indentation happens inside these pairs. + +@defopt TeX-indent-open-delimiters +This variable contains additional opening delimiters which increase +indentation. For example add @code{[} to this variable to get text after +a square bracket indented. +@end defopt + +@defopt TeX-indent-close-delimiters +This is the accompanying variable to @code{TeX-indent-open-delimiters} +decreasing the indentation again. This variable should contain @code{]} +if @code{TeX-indent-open-delimiters} is set like described above. +@end defopt + +@noindent +Note that this is an opt-in feature, both variables are initially set to +an empty string. That is because it introduces non-trivial side effects +to include @code{[} and @code{]} in @code{TeX-indent-open-delimiters} and +@code{TeX-indent-close-delimiters}; if you only have an opening square +bracket in your text without closing it, wrong indentation persists in the +following text. For example, in math expression, half-open intervals are +frequently written as @samp{[0,10)} or @samp{[0,10[}. In such cases, you +can put the closing part as a comment in the same line in order to have +correct indentation after that: +@example +$[0,10)$ % ] +$[0,10[$ % ]] +@end example + +Another example is @samp{\left}-@samp{\right} pair in equations. Similar +workarounds are available: +@example +\begin@{equation@} + \left[ % ] + xyz + \right] % [ + abc +\end@{equation@} +@end example + +You can include parens @samp{()} also in @code{TeX-indent-open-delimiters} +and @code{TeX-indent-close-delimiters} to enable indent inside them. Be +prepared for similar side effects when you do. + +Note that commented curly braces @code{@{} and @code{@}} aren't counted +when @AUCTeX{} computes indentation. + +@node Filling +@section Filling +@cindex Filling +@cindex Formatting +@cindex Reformatting +@cindex Refilling +@findex auto-fill-mode +@findex turn-on-auto-fill +@vindex fill-column + +Filling deals with the insertion of line breaks to prevent lines from +becoming wider than what is specified in @code{fill-column}. The +linebreaks will be inserted automatically if @code{auto-fill-mode} is +enabled. In this case the source is not only filled but also indented +automatically as you write it. + +@code{auto-fill-mode} can be enabled for @AUCTeX{} by calling +@code{turn-on-auto-fill} in one of the hooks @AUCTeX{} is running. +@xref{Modes and Hooks}. As an example, if you want to enable +@code{auto-fill-mode} in @code{LaTeX-mode}, put the following into your +init file: + +@lisp +(add-hook 'LaTeX-mode-hook #'turn-on-auto-fill) +@end lisp + +You can manually fill explicitly marked regions, paragraphs, +environments, complete sections, or the whole buffer. (Note that manual +filling in @AUCTeX{} will indent the start of the region to be filled in +contrast to many other Emacs modes.) + +There are some syntactical constructs which are handled specially with +regard to filling. These are so-called @dfn{code comments} and +@dfn{paragraph commands}. + +Code comments are comments preceded by code or text in the same line. +Upon filling a region, code comments themselves will not get filled. +Filling is done from the start of the region to the line with the code +comment and continues after it. In order to prevent overfull lines in +the source code, a linebreak will be inserted before the last +non-comment word by default. This can be changed by customizing +@code{LaTeX-fill-break-before-code-comments}. If you have overfull +lines with code comments you can fill those explicitly by calling +@code{LaTeX-fill-paragraph} or pressing @kbd{M-q} with the cursor +positioned on them. This will add linebreaks in the comment and indent +subsequent comment lines to the column of the comment in the first line +of the code comment. In this special case @kbd{M-q} only acts on the +current line and not on the whole paragraph. + +Lines with @samp{\par} are treated similarly to code comments, +i.e.@: @samp{\par} will be treated as paragraph boundary which should not +be followed by other code or text. But it is not treated as a real +paragraph boundary like an empty line where filling a paragraph would +stop. + +Paragraph commands like @samp{\section} or @samp{\noindent} (the list of +commands is defined by @code{LaTeX-paragraph-commands}) are often to be +placed in their own line(s). This means they should not be consecuted +with any preceding or following adjacent lines of text. @AUCTeX{} will +prevent this from happening if you do not put any text except another +macro after the end of the last brace of the respective macro. If +there is other text after the macro, @AUCTeX{} regards this as a sign +that the macro is part of the following paragraph. +@vindex LaTeX-paragraph-commands + +Here are some examples: + +@example +\begin@{quote@} + text text text text +@end example + +@example +\begin@{quote@}\label@{foo@} + text text text text +@end example + +If you press @kbd{M-q} on the first line in both examples, nothing will +change. But if you write + +@example +\begin@{quote@} text + text text text text +@end example +@noindent +and press @kbd{M-q}, you will get + +@example +\begin@{quote@} text text text text text +@end example + +Besides code comments and paragraph commands, another speciality of +filling in @AUCTeX{} involves commented lines. You should be aware that +these comments are treated as islands in the rest of the @LaTeX{} code +if syntactic filling is enabled. This means, for example, if you try to +fill an environment with @code{LaTeX-fill-environment} and have the +cursor placed on a commented line which does not have a surrounding +environment inside the comment, @AUCTeX{} will report an error. +@findex LaTeX-fill-environment + +The relevant commands and variables with regard to filling are: + +@table @kbd +@item C-c C-q C-p +@kindex C-c C-q C-p +@findex LaTeX-fill-paragraph +@code{LaTeX-fill-paragraph} will fill and indent the current paragraph. + +@item M-q +@kindex M-q +Alias for @kbd{C-c C-q C-p} + +@item C-c C-q C-e +@kindex C-c C-q C-e +@findex LaTeX-fill-environment +@code{LaTeX-fill-environment} will fill and indent the current +environment. This may e.g.@: be the `document' environment, in which case +the entire document will be formatted. + +@item C-c C-q C-s +@kindex C-c C-q C-s +@findex LaTeX-fill-section +@code{LaTeX-fill-section} will fill and indent the current logical +sectional unit. + +@item C-c C-q C-r +@kindex C-c C-q C-r +@findex LaTeX-fill-region +@code{LaTeX-fill-region} will fill and indent the current region. +@end table + +@defopt LaTeX-fill-break-at-separators +List of separators before or after which respectively linebreaks will +be inserted if they do not fit into one line. The separators can be +curly braces, brackets, switches for inline math (@samp{$}, @samp{\(}, +@samp{\)}) and switches for display math (@samp{\[}, @samp{\]}). Such +formatting can be useful to make macros and math more visible or to +prevent overfull lines in the @LaTeX{} source in case a package for +displaying formatted @TeX{} output inside the Emacs buffer, like +preview-latex, is used. +@end defopt + +@defopt LaTeX-fill-break-before-code-comments +Code comments are comments preceded by some other text in the same line. +When a paragraph containing such a comment is to be filled, the comment +start will be seen as a border after which no line breaks will be +inserted in the same line. If the option +@code{LaTeX-fill-break-before-code-comments} is enabled (which is the +default) and the comment does not fit into the line, a line break will +be inserted before the last non-comment word to minimize the chance that +the line becomes overfull. +@end defopt + +@defopt LaTeX-fill-excluded-macros +A list of macro names (without leading backslash) for whose arguments +filling should be disabled. Typically, you will want to add macros here +which have long, multi-line arguments. An example is +@code{\pgfplotstabletypeset} from the pgfplotstable package which is +used as shown in the following listing: + +@verbatim +\pgfplotstabletypeset[skip first n=4]{% + XYZ Format, + Version 1.234 + Date 2010-09-01 + @author Mustermann + A B C + 1 2 3 + 4 5 6 +} +@end verbatim +@end defopt + +@node Display +@chapter Controlling Screen Display + +It is often desirable to get visual help of what markup code in a text +actually does without having to decipher it explicitly. For this +purpose Emacs and @AUCTeX{} provide font locking (also known as syntax +highlighting) which visually sets off markup code like macros or +environments by using different colors or fonts. For example text to be +typeset in italics can be displayed with an italic font in the editor as +well, or labels and references get their own distinct color. + +While font locking helps you grasp the purpose of markup code and +separate markup from content, the markup code can still be distracting. +@AUCTeX{} lets you hide those parts and show them again at request with +its built-in support for hiding macros and environments which we call +folding here. + +Besides folding of macros and environments, @AUCTeX{} provides support +for Emacs' outline mode which lets you narrow the buffer content to +certain sections of your text by hiding the parts not belonging to these +sections. + +Moreover, you can focus in a specific portion of the code by narrowing +the buffer to the desired region. @AUCTeX{} provides also functions to +narrow the buffer to the current group and to @LaTeX{} environments. + +@AUCTeX{} also provides some WYSIWYG features. + +First, you can customize @code{font-latex-fontify-script} to enable +special formatting of @code{^} superscripts and @code{_} subscripts +(@pxref{Font Locking}). + +Secondly, @AUCTeX{} with GNU Emacs 25 or later can display certain math +macros using Unicode characters, e.g., @code{\alpha} as α. This is +called prettification and is lightweight and reasonable robust +(@pxref{Prettifying}). + +A more accurate approach is provided by @previewlatex{}, a subsystem of +@AUCTeX{}, see @ref{Top,,Introduction,preview-latex,The @previewlatex{} +Manual}. This system uses @LaTeX{} to generate images that are then +displayed in your buffer. It is extremely accurate but can be fragile +with some packages (like older pgf versions). + +Please note that you can use prettification and @previewlatex{} together. + +@menu +* Font Locking:: Font Locking +* Folding:: Folding Macros and Environments +* Outline:: Outlining the Document +* Narrowing:: Restricting display and editing to a portion of the buffer +* Prettifying:: Displaying Greek and math macros as Unicode characters +@end menu + +@node Font Locking +@section Font Locking +@cindex Font Locking +@cindex Syntax Highlighting +@cindex font-latex + +Font locking is supposed to improve readability of the source code by +highlighting certain keywords with different colors or fonts. It +thereby lets you recognize the function of markup code to a certain +extent without having to read the markup command. For general +information on controlling font locking with Emacs' Font Lock mode, see +@ref{Font Lock, , Font Lock Mode, emacs, GNU Emacs Manual}. + +@defopt TeX-install-font-lock +Once font locking is enabled globally or for the major modes provided by +@AUCTeX{}, the font locking patterns and functionality of @fontlatex{} +are activated by default. You can switch to a different font locking +scheme or disable font locking in @AUCTeX{} by customizing the variable +@code{TeX-install-font-lock}. + +Besides @fontlatex{} @AUCTeX{} ships with a scheme which is derived +from Emacs' default @LaTeX{} mode and activated by choosing +@code{tex-font-setup}. Be aware that this scheme is not coupled with +@AUCTeX{}'s style system and not the focus of development. Therefore +and due to @fontlatex{} being much more feature-rich the following +explanations will only cover @fontlatex{}. + +In case you want to hook in your own fontification scheme, you can +choose @code{other} and insert the name of the function which sets up +your font locking patterns. If you want to disable fontification in +@AUCTeX{} completely, choose @code{ignore}. +@end defopt + +@fontlatex{} provides many options for customization which are +accessible with @kbd{M-x customize-group @key{RET} font-latex @key{RET}}. For this +description the various options are explained in conceptional groups. + +@menu +* Fontification of macros:: Fontification of macros +* Fontification of quotes:: Fontification of quotes +* Fontification of math:: Fontification of math constructs +* Verbatim content:: Verbatim macros and environments +* Faces:: Faces used by font-latex +* Known problems:: Known fontification problems +@end menu + +@node Fontification of macros +@subsection Fontification of macros + +Highlighting of macros can be customized by adapting keyword lists which +can be found in the customization group @code{font-latex-keywords}. + +Three types of macros can be handled differently with respect to +fontification: + +@enumerate +@item +Commands of the form @samp{\foo[bar]@{baz@}} which consist of the macro +itself, optional arguments in square brackets and mandatory arguments in +curly braces. For the command itself the face +@code{font-lock-keyword-face} will be used and for the optional +arguments the face @code{font-lock-variable-name-face}. The face +applied to the mandatory argument depends on the macro class represented +by the respective built-in variables. +@item +Declaration macros of the form @samp{@{\foo text@}} which consist of the +macro which may be enclosed in a @TeX{} group together with text to be +affected by the macro. In case a @TeX{} group is present, the macro +will get the face @code{font-lock-keyword-face} and the text will get +the face configured for the respective macro class. If no @TeX{} group +is present, the latter face will be applied to the macro itself. +@item +Simple macros of the form @samp{\foo} which do not have any arguments or +groupings. The respective face will be applied to the macro itself. +@end enumerate + +Customization variables for @samp{\foo[bar]@{baz@}} type macros allow +both the macro name and the sequence of arguments to be specified. The +latter is done with a string which can contain the characters +@table @samp +@item * +indicating the existence of a starred variant for the macro, +@item [ +for optional arguments in brackets, +@item @{ +for mandatory arguments in braces, +@item \ +for mandatory arguments consisting of a single macro and +@item | +as a prefix indicating that two alternatives are following. +@end table +For example the specifier for @samp{\documentclass} would be @samp{[@{} +because the macro has one optional followed by one mandatory argument. +The specifier for @samp{\newcommand} would be @samp{*|@{\[[@{} because +there is a starred variant, the mandatory argument following the macro +name can be a macro or a @TeX{} group which can be followed by two +optional arguments and the last token is a mandatory argument in braces. + +Customization variables for the @samp{@{\foo text@}} and @samp{\foo} +types are simple lists of strings where each entry is a macro name +(without the leading backslash). + +@subheading General macro classes + +@fontlatex{} provides keyword lists for different macro classes which +are described in the following table: + +@vindex font-latex-match-function-keywords +@vindex font-latex-match-reference-keywords +@vindex font-latex-match-textual-keywords +@vindex font-latex-match-variable-keywords +@vindex font-latex-match-warning-keywords +@table @code +@item font-latex-match-function-keywords +Keywords for macros defining or related to functions, like +@samp{\newcommand}.@* +Type: @samp{\macro[...]@{...@}}@* +Face: @code{font-lock-function-name-face} + +@item font-latex-match-reference-keywords +Keywords for macros defining or related to references, like +@samp{\ref}.@* +Type: @samp{\macro[...]@{...@}}@* +Face: @code{font-lock-constant-face} + +@item font-latex-match-textual-keywords +Keywords for macros specifying textual content, like @samp{\caption}.@* +Type: @samp{\macro[...]@{...@}}@* +Face: @code{font-lock-type-face} + +@item font-latex-match-variable-keywords +Keywords for macros defining or related to variables, like +@samp{\setlength}.@* +Type: @samp{\macro[...]@{...@}}@* +Face: @code{font-lock-variable-name-face} + +@item font-latex-match-warning-keywords +Keywords for important macros, e.g.@: affecting line or page break, like +@samp{\clearpage}.@* +Type: @samp{\macro}@* +Face: @code{font-latex-warning-face} +@end table + +@subheading Sectioning commands +@cindex Sectioning commands, fontification of + +Sectioning commands are macros like @samp{\chapter} or @samp{\section}. +For these commands there are two fontification schemes which may be +selected by customizing the variable @code{font-latex-fontify-sectioning}. + +@defopt font-latex-fontify-sectioning +@c FIXME: Is @vindex correct? +@vindex font-latex-sectioning-0-face +@vindex font-latex-sectioning-1-face +@vindex font-latex-sectioning-2-face +@vindex font-latex-sectioning-3-face +@vindex font-latex-sectioning-4-face +@vindex font-latex-sectioning-5-face +Per default sectioning commands will be shown in a larger, proportional +font, which corresponds to a number for this variable. The font size +varies with the sectioning level, e.g.@: @samp{\part} +(@code{font-latex-sectioning-0-face}) has a larger font than +@samp{\paragraph} (@code{font-latex-sectioning-5-face}). Typically, +values from 1.05 to 1.3 for @code{font-latex-fontify-sectioning} give +best results, depending on your font setup. If you rather like to use +the base font and a different color, set the variable to the symbol +@samp{color}. In this case the face @code{font-lock-type-face} will be +used to fontify the argument of the sectioning commands. +@end defopt + +@vindex font-latex-match-sectioning-0-keywords +@vindex font-latex-match-sectioning-1-keywords +@vindex font-latex-match-sectioning-2-keywords +@vindex font-latex-match-sectioning-3-keywords +@vindex font-latex-match-sectioning-4-keywords +@vindex font-latex-match-sectioning-5-keywords +You can make @fontlatex{} aware of your own sectioning commands be +adding them to the keyword lists: +@code{font-latex-match-sectioning-0-keywords} +(@code{font-latex-sectioning-0-face}) @dots{} +@code{font-latex-match-sectioning-5-keywords} +(@code{font-latex-sectioning-5-face}). + +@vindex font-latex-slide-title-face +@vindex font-latex-match-slide-title-keywords +Related to sectioning there is special support for slide titles which +may be fontified with the face @code{font-latex-slide-title-face}. You +can add macros which should appear in this face by customizing the +variable @code{font-latex-match-slide-title-keywords}. + +@subheading Commands for changing fonts + +@LaTeX{} provides various macros for changing fonts or font attributes. +For example, you can select an italic font with @samp{\textit@{...@}} or +bold with @samp{\textbf@{...@}}. An alternative way to specify these +fonts is to use special macros in @TeX{} groups, like @samp{@{\itshape +...@}} for italics and @samp{@{\bfseries ...@}} for bold. As mentioned +above, we call the former variants commands and the latter +declarations. + +Besides the macros for changing fonts provided by @LaTeX{} there is an +infinite number of other macros---either defined by yourself for logical +markup or defined by macro packages---which affect the font in the +typeset text. While @LaTeX{}'s built-in macros and macros of packages +known by @AUCTeX{} are already handled by @fontlatex{}, different +keyword lists per type style and macro type are provided for entering +your own macros which are listed in the table below. + +@vindex font-latex-match-bold-command-keywords +@vindex font-latex-match-italic-command-keywords +@vindex font-latex-match-math-command-keywords +@vindex font-latex-match-type-command-keywords +@vindex font-latex-match-bold-declaration-keywords +@vindex font-latex-match-italic-declaration-keywords +@vindex font-latex-match-type-declaration-keywords +@table @code +@item font-latex-match-bold-command-keywords +Keywords for commands specifying a bold type style.@* +Face: @code{font-latex-bold-face} +@item font-latex-match-italic-command-keywords +Keywords for commands specifying an italic font.@* +Face: @code{font-latex-italic-face} +@item font-latex-match-math-command-keywords +Keywords for commands specifying a math font.@* +Face: @code{font-latex-math-face} +@item font-latex-match-type-command-keywords +Keywords for commands specifying a typewriter font.@* +Face: @code{font-lock-type-face} +@item font-latex-match-bold-declaration-keywords +Keywords for declarations specifying a bold type style.@* +Face: @code{font-latex-bold-face} +@item font-latex-match-italic-declaration-keywords +Keywords for declarations specifying an italic font.@* +Face: @code{font-latex-italic-face} +@item font-latex-match-type-declaration-keywords +Keywords for declarations specifying a typewriter font.@* +Face: @code{font-latex-type-face} +@end table + +@subheading Deactivating defaults of built-in keyword classes + +@vindex font-latex-deactivated-keyword-classes +@fontlatex{} ships with predefined lists of keywords for the classes +described above. You can disable these defaults per class by +customizing the variable @code{font-latex-deactivated-keyword-classes}. +This is a list of strings for keyword classes to be deactivated. Valid +entries are "warning", "variable", "biblatexnoarg", "biblatex", +"reference", "function" , "sectioning-0", "sectioning-1", +"sectioning-2", "sectioning-3", "sectioning-4", "sectioning-5", +"slide-title", "textual", "bold-command", "italic-command", +"math-command", "type-command", "bold-declaration", +"italic-declaration", "type-declaration". + +You can also get rid of certain keywords only. For example if you want +to remove highlighting of footnotes as references you can put the +following stanza into your init file: + +@lisp +(eval-after-load "font-latex" + '(setq-default + font-latex-match-reference-keywords-local + (remove (assoc-string "footnote" + font-latex-match-reference-keywords-local) + font-latex-match-reference-keywords-local))) +@end lisp + +But note that this means fiddling with @fontlatex{}'s internals and is +not guaranteed to work in future versions of @fontlatex{}. + +@subheading User-defined keyword classes + +In case the customization options explained above do not suffice for +your needs, you can specify your own keyword classes by customizing the +variable @code{font-latex-user-keyword-classes}. + +@defopt font-latex-user-keyword-classes +Every keyword class consists of four parts, a name, a list of keywords, +a face and a specifier for the type of macros to be highlighted. + +When adding new entries, you have to use unique values for the class +names, i.e.@: they must not clash with names of the built-in keyword +classes or other names given by you. Additionally the names must not +contain spaces. + +The list of keywords defines which commands and declarations should be +covered by the keyword class. A keyword can either be a simple command +name omitting the leading backslash or a list consisting of the command +name and a string specifying the sequence of arguments for the command. + +The face argument can either be an existing face or face attributes +made by you. + +There are three alternatives for the type of keywords---``Command with +arguments'', ``Declaration inside @TeX{} group'' and ``Command without +arguments''---which correspond with the macro types explained above. +@end defopt + +@node Fontification of quotes +@subsection Fontification of quotes +@cindex Quotes, fontification of + +Text in quotation marks is displayed with the face +@code{font-latex-string-face}. Besides the various forms of opening and +closing double and single quotation marks, so-called guillemets (<<, >>) +can be used for quoting. Because there are two styles of using +them---French style: << text >>; German style: >>text<<---you can +customize the variable @code{font-latex-quotes} to tell @fontlatex{} +which type you are using if the correct value cannot be derived from +document properties. + +@defopt font-latex-quotes +The default value of @code{font-latex-quotes} is @samp{auto} which means +that @fontlatex{} will try to derive the correct type of quotation mark +matching from document properties like the language option supplied to +the babel @LaTeX{} package. + +If the automatic detection fails for you and you mostly use one specific +style you can set it to a specific language-dependent value as well. +Set the value to @samp{german} if you are using >>German quotes<< and to +@samp{french} if you are using << French quotes >>. @fontlatex{} will +recognize the different ways these quotes can be given in your source +code, i.e.@: (@samp{"<}, @samp{">}), (@samp{<<}, @samp{>>}) and the +respective 8-bit variants. + +If you set @code{font-latex-quotes} to nil, quoted content will not be +fontified. +@end defopt + + +@node Fontification of math +@subsection Fontification of mathematical constructs +@cindex Math, fontification of +@cindex Subscript, fontification of +@cindex Superscript, fontification of + +@vindex font-latex-match-math-command-keywords +@vindex font-latex-math-environments +@vindex texmathp-tex-commands +@vindex texmathp-tex-commands-default +In @LaTeX{} mathematics can be indicated by a variety of different +methods: toggles (like dollar signs), macros and environments. Math +constructs known by @fontlatex{} are displayed with the face +@code{font-latex-math-face}. Support for dollar signs and shorthands +like @samp{\(...\)} or @samp{\[...\]} is built-in and not customizable. +Support for other math macros and environments can be adapted by +customizing the variables @code{font-latex-match-math-command-keywords} +and @code{texmathp-tex-commands} respectively. It is no longer +recommended to customize @code{font-latex-math-environments}. + +To convert your customization in @code{font-latex-math-environments} +into @code{texmathp-tex-commands}, please register your own math +environments, together with starred variants if any, as entries of +@code{env-on} type in @code{texmathp-tex-commands}, then clear out +@code{font-latex-math-environments}. You have to restart Emacs for this +new customization to take effect for fontification. + +In order to make math constructs more readable, @fontlatex{} displays +subscript and superscript parts in a smaller font and raised or lowered +respectively. This fontification feature can be controlled with the +variables @code{font-latex-fontify-script} and +@code{font-latex-script-display}. + +@defopt font-latex-fontify-script +If non-nil, fontify subscript and superscript strings. Concretely, this +means that the scripts are raised or lowered. + +Another possiblity is setting this variable to the symbol +@code{multi-level}. In this case, in a formula @i{x^@{y^z@}}, @i{y} is +raised above and smaller than @i{x}, and @i{z} is raised above and +smaller than @i{y}. With many script levels, the text might become too +small to be readable. (See @code{font-latex-fontify-script-max-level} +below.) + +Lastly, you can set this variable to @code{invisible} whose behavior is +like @code{multi-level}, and in addition the super-/subscript characters +@i{^} and @i{_} are not displayed. +@end defopt + +@vindex font-latex-superscript-face +@vindex font-latex-subscript-face +@defopt font-latex-fontify-script-max-level +Maximum scriptification level for which script faces are applied. + +The faces @code{font-latex-superscript-face} and +@code{font-latex-subscript-face} define custom @code{:height} values < +1.0. Therefore, scripts are displayed with a slightly smaller font than +normal math text. If @code{font-latex-fontify-script} is +@code{multi-level} or @code{invisible}, the font size becomes too small +to be readable after a few levels. This option allows to specify the +maximum level after which the size of the script text won’t be shrunken +anymore. + +For example, in the expression @i{x^@{y^@{z^a_b@}@}}, @i{x} has +scriptification level 0, @i{y} has level 1, @i{z} has level 2, and both +@i{a} and @i{b} have scriptification level 3. + +If @code{font-latex-fontify-script-max-level} was 2, then @i{z}, @i{a}, +and @i{b} would have the same font size. If it was 3 or more, then +@i{a} and @i{b} were smaller than @i{z} just in the same way as @i{z} is +smaller than @i{y} and @i{y} is smaller than @i{x}. +@end defopt + +@vindex font-latex-script-char-face +The script characters @samp{^} and @samp{_} themselves are also +fontified with an own face named @code{font-latex-script-char-face}. + +@defopt font-latex-script-display +Display specification for subscript and superscript content. The car is +used for subscript, the cdr is used for superscript. The feature is +implemented using so-called display properties. For information on what +exactly to specify for the values, see @ref{Other Display Specs, , Other +Display Specifications, elisp, GNU Emacs Lisp Reference Manual}. +@end defopt + +@node Verbatim content +@subsection Verbatim macros and environments +@cindex Verbatim, fontification of + +Usually it is not desirable to have content to be typeset verbatim +highlighted according to @LaTeX{} syntax. Therefore this content will +be fontified uniformly with the face @code{font-latex-verbatim-face}. + +@vindex LaTeX-verbatim-macros-with-delims +@vindex LaTeX-verbatim-macros-with-braces +@vindex LaTeX-verbatim-environments +@fontlatex{} differentiates three different types of verbatim +constructs for fontification. Macros with special characters like | as +delimiters, macros with braces, and environments. Which macros and +environments are recognized is controlled by the variables +@code{LaTeX-verbatim-macros-with-delims}, +@code{LaTeX-verbatim-macros-with-braces}, and +@code{LaTeX-verbatim-environments} respectively. + +@node Faces +@subsection Faces used by @fontlatex{} +@cindex Faces + +In case you want to change the colors and fonts used by @fontlatex{} +please refer to the faces mentioned in the explanations above and use +@kbd{M-x customize-face @key{RET} <face> @key{RET}}. All faces defined by +@fontlatex{} are accessible through a customization group by typing +@kbd{M-x customize-group @key{RET} font-latex-highlighting-faces @key{RET}}. + +@node Known problems +@subsection Known fontification problems +@cindex Dollar signs, color bleed with +@cindex Math, fontification problems with + +In certain cases the fontification machinery fails to interpret buffer +contents correctly. This can lead to color bleed, i.e.@: large parts of a +buffer get fontified with an inappropriate face. A typical situation +for this to happen is the use of a dollar sign (@samp{$}) in a verbatim +macro or environment. If @fontlatex{} is not aware of the verbatim +construct, it assumes the dollar sign to be a toggle for mathematics and +fontifies the following buffer content with the respective face until it +finds a closing dollar sign or till the end of the buffer. + +As a remedy you can make the verbatim construct known to @fontlatex{} +(@pxref{Verbatim content}). If this is not possible, you can insert a +commented dollar sign (@samp{%$}) at the next suitable end of line as a +quick workaround. In docTeX documents, @samp{^^A$} is also available +for similar purpose. + +@node Folding +@section Folding Macros and Environments +@cindex Outlining +@cindex Folding +@cindex Reveal +@cindex Auto-Reveal +@cindex Hide Macros + +A popular complaint about markup languages like @TeX{} and @LaTeX{} is +that there is too much clutter in the source text and that one cannot +focus well on the content. There are macros where you are only +interested in the content they are enclosing, like font specifiers where +the content might already be fontified in a special way by font locking. +Or macros the content of which you only want to see when actually +editing it, like footnotes or citations. Similarly you might find +certain environments or comments distracting when trying to concentrate +on the body of your document. + +With @AUCTeX{}'s folding functionality you can collapse those items and +replace them by a fixed string, the content of one of their arguments, +or a mixture of both. If you want to make the original text visible +again in order to view or edit it, move point sideways onto the +placeholder (also called display string) or left-click with the mouse +pointer on it. The +macro or environment will unfold automatically, stay open as long as +point is inside of it and collapse again once you move point out of it. +(Note that folding of environments currently does not work in every +@AUCTeX{} mode.) + +In order to use this feature, you have to activate @code{TeX-fold-mode} +which will activate the auto-reveal feature and the necessary commands +to hide and show macros and environments. You can activate the mode in +a certain buffer by typing the command @kbd{M-x TeX-fold-mode @key{RET}} or +using the keyboard shortcut @kbd{C-c C-o C-f}. If you want to use it +every time you edit a @LaTeX{} document, add it to a hook: +@findex TeX-fold-mode +@kindex C-c C-o C-f + +@lisp +(add-hook 'LaTeX-mode-hook (lambda () + (TeX-fold-mode 1))) +@end lisp + +If it should be activated in all @AUCTeX{} modes, use +@code{TeX-mode-hook} instead of @code{LaTeX-mode-hook}. + +Once the mode is active there are several commands available to hide +and show macros, environments and comments: + +@deffn Command TeX-fold-buffer +@kindex C-c C-o C-b +(@kbd{C-c C-o C-b}) Hide all foldable items in the current buffer +according to the setting of @code{TeX-fold-type-list}. + +If you want to have this done automatically every time you open a file, +add it to a hook and make sure the function is called after font locking +is set up for the buffer. The following code should accomplish this: + +@lisp +(add-hook 'find-file-hook #'TeX-fold-buffer t) +@end lisp + +The command can be used any time to refresh the whole buffer and fold +any new macros and environments which were inserted after the last +invocation of the command. +@end deffn + +@defopt TeX-fold-type-list +List of symbols determining the item classes to consider for folding. +This can be macros, environments and comments. Per default only macros +and environments are folded. +@end defopt + +@defopt TeX-fold-force-fontify +In order for all folded content to get the right faces, the whole buffer +has to be fontified before folding is carried out. +@code{TeX-fold-buffer} therefore will force fontification of unfontified +regions. As this will prolong the time folding takes, you can prevent +forced fontification by customizing the variable +@code{TeX-fold-force-fontify}. +@end defopt + +@defopt TeX-fold-auto +By default, a macro inserted with @code{TeX-insert-macro} (@kbd{C-c +C-m}) will not be folded. Set this variable to a non-nil value to +aumatically fold macros as soon as they are inserted. +@end defopt + +@defopt TeX-fold-preserve-comments +By default items found in comments will be folded. If your comments +often contain unfinished code this might lead to problems. Give this +variable a non-nil value and foldable items in your comments will be +left alone. +@end defopt + +@defopt TeX-fold-unfold-around-mark +When this variable is non-nil and there is an active regione, text +around the mark will be kept unfolded. +@end defopt + +@deffn Command TeX-fold-region +@kindex C-c C-o C-r +(@kbd{C-c C-o C-r}) Hide all configured macros in the marked region. +@end deffn + +@deffn Command TeX-fold-paragraph +@kindex C-c C-o C-p +(@kbd{C-c C-o C-p}) Hide all configured macros in the paragraph +containing point. +@end deffn + +@deffn Command TeX-fold-macro +@kindex C-c C-o C-m +(@kbd{C-c C-o C-m}) Hide the macro on which point currently is located. +If the name of the macro is found in @code{TeX-fold-macro-spec-list}, +the respective display string will be shown instead. If it is not +found, the name of the macro in sqare brackets or the default string for +unspecified macros (@code{TeX-fold-unspec-macro-display-string}) will be +shown, depending on the value of the variable +@code{TeX-fold-unspec-use-name}. +@end deffn + +@deffn Command TeX-fold-env +@kindex C-c C-o C-e +(@kbd{C-c C-o C-e}) Hide the environment on which point currently is +located. The behavior regarding the display string is analogous to +@code{TeX-fold-macro} and determined by the variables +@code{TeX-fold-env-spec-list} and +@code{TeX-fold-unspec-env-display-string} respectively. +@end deffn + +@deffn Command TeX-fold-math +Hide the math macro on which point currently is located. If the name of +the macro is found in @code{TeX-fold-math-spec-list}, the respective +display string will be shown instead. If it is not found, the name of +the macro in sqare brackets or the default string for unspecified macros +(@code{TeX-fold-unspec-macro-display-string}) will be shown, depending +on the value of the variable @code{TeX-fold-unspec-use-name}. +@end deffn + +@deffn Command TeX-fold-comment +@kindex C-c C-o C-c +(@kbd{C-c C-o C-c}) Hide the comment point is located on. +@end deffn + +@deffn Command TeX-fold-clearout-buffer +@kindex C-c C-o b +(@kbd{C-c C-o b}) Permanently unfold all macros and environments in the +current buffer. +@end deffn + +@deffn Command TeX-fold-clearout-region +@kindex C-c C-o r +(@kbd{C-c C-o r}) Permanently unfold all macros and environments in the +marked region. +@end deffn + +@deffn Command TeX-fold-clearout-paragraph +@kindex C-c C-o p +(@kbd{C-c C-o p}) Permanently unfold all macros and environments in the +paragraph containing point. +@end deffn + +@deffn Command TeX-fold-clearout-item +@kindex C-c C-o i +(@kbd{C-c C-o i}) Permanently show the macro or environment on which +point currently is located. In contrast to temporarily opening the +macro when point is moved sideways onto it, the macro will be +permanently unfolded and will not collapse again once point is leaving +it. +@end deffn + +@deffn Command TeX-fold-dwim +@kindex C-c C-o C-o +(@kbd{C-c C-o C-o}) Hide or show items according to the current context. +If there is folded content, unfold it. If there is a marked region, +fold all configured content in this region. If there is no folded +content but a macro or environment, fold it. +@end deffn + +@vindex TeX-fold-command-prefix +In case you want to use a different prefix than @kbd{C-c C-o} for these +commands you can customize the variable @code{TeX-fold-command-prefix}. +(Note that this will not change the key binding for activating the +mode.) + +The commands above will only take macros or environments into +consideration which are specified in the variables +@code{TeX-fold-macro-spec-list} or @code{TeX-fold-env-spec-list} +respectively. + +@defopt TeX-fold-macro-spec-list +List of replacement specifiers and macros to fold. The specifier can be +a string, an integer or a function symbol. + +If you specify a string, it will be used as a display replacement for +the whole macro. Numbers in braces, brackets, parens or angle brackets +will be replaced by the respective macro argument. For example +@samp{@{1@}} will be replaced by the first mandatory argument of the +macro. One can also define alternatives within the specifier which are +used if an argument is not found. Alternatives are separated by +@samp{||}. They are most useful with optional arguments. As an +example, the default specifier for @samp{\item} is @samp{[1]:||*} which +means that if there is an optional argument, its value is shown followed +by a colon. If there is no optional argument, only an asterisk is used +as the display string. + +If you specify a number as the first element, the content of the +respective mandatory argument of a @LaTeX{} macro will be used as the +placeholder. + +If the first element is a function symbol, the function will be called +with all mandatory arguments of the macro and the result of the function +call will be used as a replacement for the macro. + +The placeholder is made by copying the text from the buffer together with +its properties, i.e.@: its face as well. If fontification has not +happened when this is done (e.g.@: because of lazy font locking) the +intended fontification will not show up. As a workaround you can leave +Emacs idle a few seconds and wait for stealth font locking to finish +before you fold the buffer. Or you just re-fold the buffer with +@code{TeX-fold-buffer} when you notice a wrong fontification. +@end defopt + +@defopt TeX-fold-env-spec-list +List of display strings or argument numbers and environments to fold. +Argument numbers refer to the @samp{\begin} statement. That means if +you have e.g.@: @samp{\begin@{tabularx@}@{\linewidth@}@{XXX@} ... +\end@{tabularx@}} and specify 3 as the argument number, the resulting +display string will be ``XXX''. +@end defopt + +@defopt TeX-fold-math-spec-list +List of display strings and math macros to fold. +@end defopt + +@vindex LaTeX-fold-macro-spec-list +@vindex LaTeX-fold-env-spec-list +@vindex LaTeX-fold-math-spec-list +The variables @code{TeX-fold-macro-spec-list}, +@code{TeX-fold-env-spec-list}, and @code{TeX-fold-math-spec-list} apply +to any @AUCTeX{} mode. If you want to make settings which are only +applied to @LaTeX{} mode, you can use the mode-specific variables +@code{LaTeX-fold-macro-spec-list}, @code{LaTeX-fold-env-spec-list}, and +@code{LaTeX-fold-math-spec-list} + +@defopt TeX-fold-unspec-macro-display-string +Default display string for macros which are not specified in +@code{TeX-fold-macro-spec-list}. +@end defopt + +@defopt TeX-fold-unspec-env-display-string +Default display string for environments which are not specified in +@code{TeX-fold-env-spec-list}. +@end defopt + +@defopt TeX-fold-unspec-use-name +If non-nil the name of the macro or environment surrounded by square +brackets is used as display string, otherwise the defaults specified in +@code{TeX-fold-unspec-macro-display-string} or +@code{TeX-fold-unspec-env-display-string} respectively. +@end defopt + +When you hover with the mouse pointer over folded content, its original +text will be shown in a tooltip or the echo area depending on Tooltip +mode being activate. In order to avoid exorbitantly big tooltips and to +cater for the limited space in the echo area the content will be cropped +after a certain amount of characters defined by the variable +@code{TeX-fold-help-echo-max-length}. + +@defopt TeX-fold-help-echo-max-length +Maximum length of original text displayed in a tooltip or the echo area +for folded content. Set it to zero in order to disable this feature. +@end defopt + + +@node Outline +@section Outlining the Document +@cindex Outlining +@cindex Headers +@cindex Sections +@cindex Overview +@cindex Folding + +@AUCTeX{} supports the standard outline minor mode using +@LaTeX{}/@ConTeXt{} sectioning commands as header lines. @xref{Outline +Mode, , Outline Mode, emacs, GNU Emacs Manual}. + +You can add your own headings by setting the variable +@code{TeX-outline-extra}. + +@defvar TeX-outline-extra +List of extra @TeX{} outline levels. + +Each element is a list with two entries. The first entry is the regular +expression matching a header, and the second is the level of the header. +A @samp{^} is automatically prepended to the regular expressions in the +list, so they must match text at the beginning of the line. + +See @code{LaTeX-section-list} or @code{ConTeXt-@var{interface}-section-list} +for existing header levels. +@end defvar + +The following example add @samp{\item} and @samp{\bibliography} headers, +with @samp{\bibliography} at the same outline level as @samp{\section}, +and @samp{\item} being below @samp{\subparagraph}. + +@lisp +(setq TeX-outline-extra + '(("[ \t]*\\\\\\(bib\\)?item\\b" 7) + ("\\\\bibliography\\b" 2))) +@end lisp + +@c FIXME: Isn't this much outdated? +You may want to check out the unbundled @file{out-xtra} package for even +better outline support. It is available from your favorite emacs lisp +archive. + +@node Narrowing +@section Narrowing + +Sometimes you want to focus your attention to a limited region of the +code. You can do that by restricting the text addressable by editing +commands and hiding the rest of the buffer with the narrowing functions, +@pxref{Narrowing,,,emacs,GNU Emacs Manual}. In addition, @AUCTeX{} +provides a couple of other commands to narrow the buffer to a group, +i.e.@: a region enclosed in a pair of curly braces, and to @LaTeX{} +environments. + +@deffn Command TeX-narrow-to-group +@kindex C-x n g +(@kbd{C-x n g}) Make text outside current group invisible. +@end deffn + +@deffn Command LaTeX-narrow-to-environment @var{count} +@kindex C-x n e +(@kbd{C-x n e}) Make text outside current environment invisible. With +optional argument @var{count} keep visible that number of enclosing +environmens. +@end deffn + +Like other standard narrowing functions, the above commands are +disabled. Attempting to use them asks for confirmation and gives you +the option of enabling them; if you enable the commands, confirmation +will no longer be required for them. + +@node Prettifying +@section Prettifying + +Emacs 25 is able to prettify symbols in programming language buffers, +@pxref{Misc for Programs,,,emacs,GNU Emacs Manual}. The canonical +example is to display @code{(lambda () ...)} as @code{(λ () ...)} in +Lisp buffers. + +@AUCTeX{} can use this feature in order to display certain math macros +and greek letters using their Unicode representation, too. For example, +the @TeX{} code @code{\alpha \times \beta} will be displayed as @code{α +× β}. When point is on one of the characters, it'll be unprettified +automatically, meaning you see the verbatim text again. For this +behaviour however you need to set +@code{prettify-symbols-unprettify-at-point} to t or @code{right-edge} +which will unprettify the symbol when point moves into or near it. + +To enable prettification in @AUCTeX{}, simply add +@code{prettify-symbols-mode} to @code{TeX-mode-hook}. If you enabled +prettification globally with @code{global-prettify-symbols-mode}, then +it's automatically enabled in @AUCTeX{}, too. + +You can also add custom symbol unicode-character pairs for +prettification by adding to @code{tex--prettify-symbols-alist}. Note +that this variable is part of Emacs' stock @code{tex-mode.el} and used +by that and @AUCTeX{}. + +@node Processing +@chapter Starting Processors, Viewers and Other Programs + +The most powerful features of @AUCTeX{} may be those allowing you to run +@TeX{}, @LaTeX{}, @ConTeXt{} and other external commands like Bib@TeX{} +and @command{makeindex} from within Emacs, viewing and printing the +results, and moreover allowing you to @emph{debug} your documents. + +@cindex tool bar, toolbar +@vindex LaTeX-enable-toolbar +@vindex plain-TeX-enable-toolbar +@vindex TeX-bar-TeX-buttons +@vindex TeX-bar-TeX-all-button-alists +@vindex TeX-bar-LaTeX-buttons +@vindex TeX-bar-LaTeX-button-alist +@AUCTeX{} comes with a special tool bar for @TeX{} and @LaTeX{} which +provides buttons for the most important commands. You can enable or +disable it by customizing the options @code{plain-TeX-enable-toolbar} +and @code{LaTeX-enable-toolbar} in the @code{TeX-tool-bar} customization +group. You can also customize the buttons by the options +@code{TeX-bar-TeX-buttons}, @code{TeX-bar-TeX-all-button-alists}, +@code{TeX-bar-LaTeX-buttons} and @code{TeX-bar-LaTeX-button-alist}. +@c FIXME: Write details about customizing tool bar. + +@menu +* Commands:: Invoking external commands. +* Viewing:: Invoking external viewers. +* Debugging:: Debugging @TeX{} and @LaTeX{} output. +* Checking:: Checking the document. +* Control:: Controlling the processes. +* Cleaning:: Cleaning intermediate and output files. +* Documentation:: Documentation about macros and packages. +@end menu + +@node Commands +@section Executing Commands +@cindex Formatting +@cindex Running @LaTeX{} +@cindex Running @TeX{} +@cindex @LaTeX{} +@cindex @TeX{} +@cindex Running commands +@cindex Default command +@cindex Header +@cindex Trailer +@cindex Setting the header +@cindex Setting the trailer +@cindex Region +@cindex Region file +@cindex Setting the default command +@cindex Commands +@cindex External Commands +@cindex Indexing +@cindex Making an index +@cindex Running @command{makeindex} +@cindex @command{makeindex} +@cindex Bib@TeX{} +@cindex Bibliography +@cindex Literature +@cindex Running Bib@TeX{} +@cindex Making a bibliography +@cindex Printing +@cindex Writing to a printer + +Formatting the document with @TeX{}, @LaTeX{} or @ConTeXt{}, viewing +with a previewer, printing the document, running Bib@TeX{}, making an +index, or checking the document with @command{lacheck} or +@command{chktex} all require running an external command. + +@menu +* Starting a Command:: Starting a Command on a Document or Region +* Selecting a Command:: Selecting and Executing a Command +* Processor Options:: Options for @TeX{} Processors +@end menu + +@node Starting a Command +@subsection Starting a Command on a Document or Region + +There are two ways to run an external command, you can either run it on +the current document with @code{TeX-command-master}, or on the current +region with @code{TeX-command-region}. A special case of running @TeX{} +on a region is @code{TeX-command-buffer} which differs from +@code{TeX-command-master} if the current buffer is not its own master +file. + +@deffn Command TeX-command-master +@kindex C-c C-c +(@kbd{C-c C-c}) Query the user for a command, and run it on the master +file associated with the current buffer. The name of the master file is +controlled by the variable @code{TeX-master}. The available commands are +controlled by the variable @code{TeX-command-list}. +@vindex TeX-master +@vindex TeX-command-list +@end deffn + +@deffn Command TeX-command-region +@kindex C-c C-r +(@kbd{C-c C-r}) Query the user for a command, and run it on the contents +of the selected region. The region contents are written into the region +file, after extracting the header and trailer from the master file. If +mark is inactive (which can happen with Transient Mark mode), use the +old region. See also the command @code{TeX-pin-region} about how to fix +a region. + +The name of the region file is controlled by the variable +@code{TeX-region}. The name of the master file is controlled by the +variable @code{TeX-master}. The header is all text up to the line +matching the regular expression @code{TeX-header-end}. The trailer is +all text from the line matching the regular expression +@code{TeX-trailer-start}. The available commands are controlled by the +variable @code{TeX-command-list}. +@vindex TeX-region +@vindex TeX-header-end +@vindex TeX-trailer-start +@vindex TeX-master +@vindex TeX-command-list +@end deffn + +@deffn Command TeX-command-buffer +@kindex C-c C-b +(@kbd{C-c C-b}) Query the user for a command, and apply it to the +contents of the current buffer. The buffer contents are written into +the region file, after extracting the header and trailer from the master +file. The command is then actually run on the region file. See above +for details. +@end deffn + +@deffn Command LaTeX-command-section +@kindex C-c C-z +(@kbd{C-c C-z}) Query the user for a command, and apply it to the +current section (or part, chapter, subsection, paragraph, or +subparagraph). What makes the current section is determined by +@code{LaTeX-command-section-level} which can be enlarged/shrunken using +@code{LaTeX-command-section-change-level} (@kbd{C-c M-z}). The given +numeric prefix arg is added to the current value of +@code{LaTeX-command-section-level}. By default, +@code{LaTeX-command-section-level} is initialized with the current +document's @code{LaTeX-largest-level}. The buffer contents are written +into the region file, after extracting the header and trailer from the +master file. The command is then actually run on the region file. See +@code{TeX-command-region} for details. +@end deffn + +It is also possible to compile automatically the whole document until it +is ready with a single command: @code{TeX-command-run-all}. + +@deffn Command TeX-command-run-all +@kindex C-c C-a +(@kbd{C-c C-a}) Compile the current document until an error occurs or it +is finished. If compilation finishes successfully, run the viewer at +the end. +@end deffn + +Here are some relevant variables. + +@defopt TeX-region +The name of the file for temporarily storing the text when formatting +the current region. +@end defopt + +@defopt TeX-header-end +A regular expression matching the end of the header. By default, this +is @samp{\begin@{document@}} in @LaTeX{} mode and @samp{%**end of +header} in plain @TeX{} mode. +@end defopt + +@defopt TeX-trailer-start +A regular expression matching the start of the trailer. By default, +this is @samp{\end@{document@}} in @LaTeX{} mode and @samp{\bye} in +plain @TeX{} mode. +@end defopt + +If you want to change the values of @code{TeX-header-end} and +@code{TeX-trailer-start} you can do this for all files by setting the +variables in a mode hook or per file by specifying them as file +variables (@pxref{File Variables,,,emacs,The Emacs Editor}). + +@deffn Command TeX-pin-region +@kindex C-c C-t C-r +(@kbd{C-c C-t C-r}) If you don't have a mode like Transient Mark mode +active, where marks get disabled automatically, the region would need to +get properly set before each call to @code{TeX-command-region}. If you +fix the current region with @kbd{C-c C-t C-r}, then it will get used for +more commands even though mark and point may change. An explicitly +activated mark, however, will always define a new region when calling +@code{TeX-command-region}. +@end deffn + +If the last process you started was +on the region, the commands described in @ref{Debugging} and +@ref{Control} will work on that process, otherwise they will work on the +process associated with the current document. + +Don't run more than one process at the same time. @AUCTeX{} doesn't +support simultaneous typeset including region typeset. Wait for the +previous process to finish before you start a new process, in particular +when you are editing multiple documents in parallel. This limitation +applies for preview by @previewlatex{} as well. + +@node Selecting a Command +@subsection Selecting and Executing a Command + +Once you started the command selection with @kbd{C-c C-c}, @kbd{C-c C-r} +or @kbd{C-c C-b} you will be prompted for the type of command. +@AUCTeX{} will try to guess which command is appropriate in the given +situation and propose it as default. Usually this is a processor like +@samp{TeX} or @samp{LaTeX} if the document was changed or a viewer if +the document was just typeset. Other commands can be selected in the +minibuffer with completion support by typing @key{TAB}. + +@vindex TeX-command-list +@vindex TeX-expand-list +The available commands are defined by the variable +@code{TeX-command-list}. Per default it includes commands for +typesetting the document (e.g.@: @samp{LaTeX}), for viewing the output +(@samp{View}), for printing (@samp{Print}), for generating an index +(@samp{Index}) or for spell checking (@samp{Spell}) to name but a few. +You can also add your own commands by adding entries to +@code{TeX-command-list}. Refer to its doc string for information about +its syntax. You might also want to look at @code{TeX-expand-list} to +learn about the expanders you can use in @code{TeX-command-list}. + +Note that the default of the variable occasionally changes. Therefore +it is advisable to add to the list rather than overwriting it. You can +do this with a call to @code{add-to-list} in your init file. For +example, if you wanted to add a command for running a program called +@samp{foo} on the master or region file, you could do this with the +following form. + +@lisp +(eval-after-load "tex" + '(add-to-list 'TeX-command-list + '("Foo" "foo %s" TeX-run-command t t :help "Run foo") + t)) +@end lisp + +As mentioned before, @AUCTeX{} will try to guess what command you want +to invoke. If you want to use another command than @samp{TeX}, +@samp{LaTeX} or whatever processor @AUCTeX{} thinks is appropriate for +the current mode, set the variable @code{TeX-command-default}. You can +do this for all files by setting it in a mode hook or per file by +specifying it as a file variable (@pxref{File Variables,,,emacs,The +Emacs Editor}). + +@defopt TeX-command-default +The default command to run in this buffer. Must be an entry in +@code{TeX-command-list}. +@end defopt + +@cindex Biber +@cindex biblatex +In case you use biblatex in a document, when automatic parsing is +enabled @AUCTeX{} checks the value of @samp{backend} option given to +biblatex at load time to decide whether to use Bib@TeX{} or Biber for +bibliography processing. Should @AUCTeX{} fail to detect the right +backend, you can use the file local @code{LaTeX-biblatex-use-Biber} +variable. +@defvr Variable LaTeX-biblatex-use-Biber +If this boolean variable is set as file local, it tells to @AUCTeX{} +whether to use Biber with biblatex. In this case, the autodetection of +the biblatex backend will be overridden. You may want to set locally +this variable if automatic parsing is not enabled. +@end defvr + +After confirming a command to execute, @AUCTeX{} will try to save any +buffers related to the document, and check if the document needs to be +reformatted. If the variable @code{TeX-save-query} is non-nil, +@AUCTeX{} will query before saving each file. By default @AUCTeX{} will +check emacs buffers associated with files in the current directory, in +one of the @code{TeX-macro-private} directories, and in the +@code{TeX-macro-global} directories. You can change this by setting the +variable @code{TeX-check-path}. + +@defopt TeX-check-path +Directory path to search for dependencies. + +If nil, just check the current file. +Used when checking if any files have changed. +@end defopt + +@cindex ispell +When performing spell checking on a document or a region (invoked +through @AUCTeX{}'s @samp{Spell} command or @kbd{M-x ispell @key{RET}}), you +want the spell checking program to skip certain macro arguments and +environments, most notably the arguments of referencing macros and the +contents of verbatim environments. The skipped parts are controlled by +variable @code{ispell-tex-skip-alists} provided by @file{ispell.el}. +@AUCTeX{} has a library which can be added to this variable depending on +the value of @code{TeX-ispell-extend-skip-list} which is set to @code{t} +by default. + +@defopt TeX-ispell-extend-skip-list +This boolean option controls whether @AUCTeX{} activates its extension +for skipping certain macro arguments and environments when spell +checking. + +When non-@code{nil}, @AUCTeX{} loads the file @file{tex-ispell.el} and +adds its content to @code{ispell-tex-skip-alists}. This library can and +will never be complete, but the interface can be used to add selected +and private macro names within your init file or on a file local basis. + +@code{ispell-tex-skip-alists} has the following structure: +@lisp +(defvar ispell-tex-skip-alists + '((;; @r{First list} + ("\\\\addcontentsline" ispell-tex-arg-end 2) + ("\\\\\\([aA]lph\\|arabic\\)" ispell-tex-arg-end) + ("\\\\makebox" ispell-tex-arg-end 0) + ("\\\\documentclass" . "\\\\begin@{document@}")) + (;; @r{Second list} + ("\\(figure\\|table\\)\\*?" ispell-tex-arg-end 0) + ("list" ispell-tex-arg-end 2) + ("verbatim\\*?" . "\\\\end@{verbatim\\*?@}"))) + "Lists of regions to be skipped in TeX mode. +First list is used raw. +Second list has key placed inside \\begin@{@}.") +@end lisp +Each item is an alist and the structure of it is described in +@code{ispell-skip-region-alist}: +@lisp +(defvar ispell-skip-region-alist + '((...)) + "Alist expressing beginning and end of regions not to spell check. +The alist key must be a regular expression. +Valid forms include: + (KEY) - just skip the key. + (KEY . REGEXP) - skip to the end of REGEXP. + REGEXP may be string or symbol. + (KEY REGEXP) - skip to end of REGEXP. REGEXP must be a string. + (KEY FUNCTION ARGS) - FUNCTION called with ARGS + returns end of region.") +@end lisp + +Let's go through the first list of @code{ispell-tex-skip-alists} line by +line: +@lisp +("\\\\addcontentsline" ispell-tex-arg-end 2) +@end lisp +@code{KEY} is the string @code{"\\\\addcontentsline"}, @code{FUNCTION} +is @code{ispell-tex-arg-end} called with @code{ARGS}, here @code{2}. +@code{ispell-tex-arg-end} is a function provided by @file{ispell.el} +which skips as many subsequent optional arguments in square brackets as +it sees and then skips @code{ARGS} number of mandatory arguments in +braces. Omitting @code{ARGS} means skip @code{1} mandatory argument. +In practice, when you have something like this in your document: +@example +\addcontentsline@{toc@}@{chapter@}@{Some text@} +@end example +The first two arguments are left out and @samp{Some text} will be spell +checked. For the next line +@lisp +("\\\\\\([aA]lph\\|arabic\\)" ispell-tex-arg-end) +@end lisp +the name of the counter as argument is skipped. Next line is +@lisp +("\\\\makebox" ispell-tex-arg-end 0) +@end lisp +where only optional arguments are skipped, the first mandatory argument +is checked, e.g. +@example +\makebox[0pt][l]@{Some text@} +@end example +Finally, the next line +@lisp +("\\\\documentclass" . "\\\\begin@{document@}")) +@end lisp +ensures that the entire preamble of a document is discarded. Second +list works the same; it is more convenient for environments since +@code{KEY} is wrapped inside @code{\begin@{@}}. + +@findex TeX-ispell-skip-setcar +@findex TeX-ispell-skip-setcdr +@AUCTeX{} provides two functions to add items to car and cdr of +@code{ispell-tex-arg-end}, namely @code{TeX-ispell-skip-setcar} and +@code{TeX-ispell-skip-setcdr}. The argument of these functions is +exactly as in @code{ispell-tex-skip-alists}. Additions can be done via +init file, e.g.: +@lisp +(eval-after-load "tex-ispell" + '(progn + (TeX-ispell-skip-setcar + '(("\\\\mymacro" ispell-tex-arg-end))) + (TeX-ispell-skip-setcdr + '(("myverbatim" . "\\\\end@{myverbatim@}"))))) +@end lisp + +Another possibility is to use file local additions at the end of your +@TeX{} file, e.g.: +@example +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% eval: (TeX-ispell-skip-setcar '(("\\\\mymacro" . "@{[-0-9]+@}"))) +%%% End: +@end example + +@findex TeX-ispell-tex-arg-end +Finally, @AUCTeX{} provides a function called +@code{TeX-ispell-tex-arg-end} which sees more arguments than +@code{ispell-tex-arg-end}. Refer to its doc string for more +information. +@end defopt + +@AUCTeX{} also provides a facility to skip the argument of in-line +verbatim macros like @samp{\Verb} from @file{fancyvrb.sty} or +@samp{\mintinline} from @file{minted.sty}. Characters delimiting the +verbatim text are stored in @code{TeX-ispell-verb-delimiters}. + +@defopt TeX-ispell-verb-delimiters +String with delimiters recognized for in-line verbatim macros. This +variable is initialized to @samp{!|#~"*/+^-}. Since this string is +used to build a character alternative inside a regular expression, +special characters @samp{^} and @samp{-} should come last. Other +characters like opening brace @samp{@{}, asterisk @samp{*} or at sign +@samp{@@} should be avoided as they are not recognized by +@file{font-latex.el}. +@end defopt + +@node Processor Options +@subsection Options for @TeX{} Processors + +There are some options you can customize affecting which processors are +invoked or the way this is done and which output they produce as a +result. These options control if @acronym{DVI} or @acronym{PDF} output +should be produced, if @TeX{} should be started in interactive or +nonstop mode, if source specials or a Sync@TeX{} file should be produced +for making inverse and forward search possible or which @TeX{} engine +should be used instead of regular @TeX{}, like PDF@TeX{}, Omega or +Xe@TeX{}, and the style error messages are printed with. + +@deffn Command TeX-PDF-mode +@kindex C-c C-t C-p +@vindex TeX-PDF-mode +@cindex PDF mode +(@kbd{C-c C-t C-p}) +This command toggles the @acronym{PDF} mode of @AUCTeX{}, a buffer-local +minor mode which is enabled by default. You can customize +@code{TeX-PDF-mode} to give it a different default or set it as a file +local variable on a per-document basis. This option usually results in +calling either PDF@TeX{} or ordinary @TeX{}. +@end deffn + +@defopt TeX-DVI-via-PDFTeX +If this is set, @acronym{DVI} will also be produced by calling +PDF@TeX{}, setting @code{\pdfoutput=0}. This makes it possible to use +PDF@TeX{} features like character protrusion even when producing +@acronym{DVI} files. Contemporary @TeX{} distributions do this anyway, +so that you need not enable the option within @AUCTeX{}. +@end defopt + +@deffn Command TeX-interactive-mode +@kindex C-c C-t C-i +@vindex TeX-interactive-mode +(@kbd{C-c C-t C-i}) This command toggles the interactive mode of +@AUCTeX{}, a global minor mode. You can customize +@code{TeX-interactive-mode} to give it a different default. In +interactive mode, @TeX{} will pause with an error prompt when errors are +encountered and wait for the user to type something. +@end deffn + +@cindex I/O correlation +@cindex Sync@TeX{} +@cindex Source specials +@cindex PDFSync +@deffn Command TeX-source-correlate-mode +@kindex C-c C-t C-s +@vindex TeX-source-correlate-mode +(@kbd{C-c C-t C-s}) Toggles support for forward and inverse search. +Forward search refers to jumping to the place in the previewed document +corresponding to where point is located in the document source and +inverse search to the other way round. @xref{I/O Correlation}. + +You can permanently activate @code{TeX-source-correlate-mode} by +customizing the variable @code{TeX-source-correlate-mode}. There is a +bunch of customization options for the mode, use @kbd{M-x +customize-group @key{RET} TeX-view @key{RET}} to find out more. + +@vindex TeX-source-correlate-method +@AUCTeX{} is aware of three different means to do I/O correlation: +source specials (only DVI output), the pdfsync @LaTeX{} package (only +PDF output) and Sync@TeX{}. The choice between source specials and +Sync@TeX{} can be controlled with the variable +@code{TeX-source-correlate-method}. + +Should you use source specials it has to be stressed @emph{very} +strongly however, that source specials can cause differences in page +breaks and spacing, can seriously interfere with various packages and +should thus @emph{never} be used for the final version of a document. +In particular, fine-tuning the page breaks should be done with source +specials switched off. +@end deffn + +Sometimes you are requested, by journal rules or packages, to compile +the document into @acronym{DVI} output. Thus, if you want a +@acronym{PDF} document in the end you can either use Xe@TeX{} engine, +see below for information about how to set engines, or compile the +document with @command{tex} and then convert to @acronym{PDF} with +@command{dvips}--@command{ps2pdf} before viewing it. In addition, +current Japanese @TeX{} engines cannot generate @acronym{PDF} directly +so they rely on @acronym{DVI}-to-@acronym{PDF} converters. Usually +@command{dvipdfmx} command is used for this purpose. You can use the +@code{TeX-PDF-from-DVI} variable to let @AUCTeX{} know you want to +generate the final @acronym{PDF} by converting a @acronym{DVI} file. + +@defopt TeX-PDF-from-DVI +This option controls if and how to produce a @acronym{PDF} file by +converting a @acronym{DVI} file. + +When @code{TeX-PDF-mode} is non-nil, if @code{TeX-PDF-from-DVI} is +non-nil too the document is compiled to @acronym{DVI} instead of +@acronym{PDF}. When the document is ready, @kbd{C-c C-c} will suggest +to run the converter to @acronym{PDF} or an intermediate format. + +If non-nil, @code{TeX-PDF-from-DVI} should be the name of the command in @code{TeX-command-list}, +as a string, used to convert the @acronym{DVI} file to @acronym{PDF} or +to an intermediate format. Values currently supported are: +@itemize +@item +@code{"Dvips"}: the @acronym{DVI} file is converted to @acronym{PS} with +@command{dvips}. After successfully running it, @command{ps2pdf} will +be the default command to convert the @acronym{PS} file to +@acronym{PDF}. +@item +@code{"Dvipdfmx"}: the @acronym{DVI} file is converted to @acronym{PDF} +with @command{dvipdfmx}. +@end itemize +(case is significant; note the uppercase @samp{D} in both strings) +When the @acronym{PDF} file is finally ready, the next suggested command +will be @samp{View} to open the viewer. + +This option can also be set as a file local variable, in order to use +this conversion on a per-document basis. + +Recall the whole sequence of @kbd{C-c C-c} commands can be replaced by +the single @kbd{C-c C-a}. +@end defopt + +@AUCTeX{} also allows you to easily select different @TeX{} engines for +processing, either by using the entries in the @samp{TeXing Options} +submenu below the @samp{Command} menu or by calling the function +@code{TeX-engine-set}. These eventually set the variable +@code{TeX-engine} which you can also modify directly. + +@defopt TeX-engine +This variable allows you to choose which @TeX{} engine should be used +for typesetting the document, i.e.@: the executables which will be used +when you invoke the @samp{TeX} or @samp{LaTeX} commands. The value +should be one of the symbols defined in @code{TeX-engine-alist-builtin} +or @code{TeX-engine-alist}. The symbols @samp{default}, @samp{xetex}, +@samp{luatex} and @samp{omega} are available from the built-in list. +@end defopt + +Note that @code{TeX-engine} is buffer-local, so setting the variable +directly or via the above mentioned menu or function will not take +effect in other buffers. If you want to activate an engine for all +@AUCTeX{} modes, set @code{TeX-engine} in your init file, e.g.@: by using +@kbd{M-x customize-option @key{RET}}. If you want to activate it for a +certain @AUCTeX{} mode only, set the variable in the respective mode +hook. If you want to activate it for certain files, set it through file +variables (@pxref{File Variables,,,emacs,The Emacs Editor}). + +@vindex TeX-command +@vindex LaTeX-command +@vindex TeX-Omega-command +@vindex LaTeX-Omega-command +@vindex ConTeXt-engine +@vindex ConTeXt-Omega-engine +@vindex TeX-engine-alist +@vindex TeX-engine-alist-builtin +Should you need to change the executable names related to the different +engine settings, there are some variables you can tweak. Those are +@code{TeX-command}, @code{LaTeX-command}, @code{TeX-Omega-command}, +@code{LaTeX-Omega-command}, @code{ConTeXt-engine} and +@code{ConTeXt-Omega-engine}. The rest of the executables is defined +directly in @code{TeX-engine-alist-builtin}. If you want to override an +entry from that, add an entry to @code{TeX-engine-alist} that starts +with the same symbol as that the entry in the built-in list and specify +the executables you want to use instead. You can also add entries to +@code{TeX-engine-alist} in order to add support for engines not covered +per default. + +@defopt TeX-engine-alist +Alist of @TeX{} engines and associated commands. Each entry is a list with +a maximum of five elements. The first element is a symbol used to +identify the engine. The second is a string describing the engine. The +third is the command to be used for plain @TeX{}. The fourth is the +command to be used for @LaTeX{}. The fifth is the command to be used for +the @option{--engine} parameter of @ConTeXt{}'s @samp{texexec} program. Each +command can either be a variable or a string. An empty string or nil +means there is no command available. +@end defopt + +In some systems, Emacs cannot inherit the @env{PATH} environment variable from +the shell and thus @AUCTeX{} may not be able to run @TeX{} commands. +Before running them, @AUCTeX{} checks if it is able to find those commands +and will warn you in case it fails. You can skip this test by changing +the option @code{TeX-check-TeX}. + +@defopt TeX-check-TeX +@vindex TeX-command +@vindex TeX-check-TeX-command-not-found +If non-nil, @AUCTeX{} will check if it is able to find a working @TeX{} +distribution before running @TeX{}, @LaTeX{}, @ConTeXt{}, etc. It +actually checks if can run @code{TeX-command} command or the shell +returns a command not found error. The error code returned by the shell +in this case can be set in @code{TeX-check-TeX-command-not-found} +option. +@end defopt + +Some @LaTeX{} packages requires the document to be compiled with a +specific engine. Notable examples are @samp{fontspec} and @samp{polyglossia} +packages, which require Lua@TeX{} and Xe@TeX{} engines. If you try to +compile a document which loads one of such packages and the set engine +is not one of those allowed you will be asked to select a different +engine before running the @LaTeX{} command. If you do not want to be +warned by @AUCTeX{} in these cases, customize the option +@code{TeX-check-engine}. + +@defopt TeX-check-engine +This boolean option controls whether @AUCTeX{} should check the correct +engine has been set before running @LaTeX{} commands. +@end defopt + +As shown above, @AUCTeX{} handles in a special way most of the main +options that can be given to the @TeX{} processors. When you need to +pass to the @TeX{} processor arbitrary options not handled by @AUCTeX{}, +you can use the file local variable @code{TeX-command-extra-options}. +@defopt TeX-command-extra-options +String with the extra options to be given to the TeX processor. For +example, if you need to enable the shell escape feature to compile a +document, add the following line to the list of local variables of the +source file: +@example +%%% TeX-command-extra-options: "-shell-escape" +@end example +By default this option is not safe as a file-local variable because a +specially crafted document compiled with shell escape enabled can be +used for malicious purposes. +@end defopt + +You can customize @AUCTeX{} to show the processor output as it is +produced. + +@defopt TeX-show-compilation +If non-nil, the output of @TeX{} compilation is shown in another window. +@end defopt + +You can instruct @TeX{} to print error messages in the form +@samp{file:line:error} which is similar to the way many compilers format them. + +@defopt TeX-file-line-error +If non-nil, @TeX{} will produce @samp{file:line:error} style error messages. +@end defopt + +@ConTeXt{} users can choose between Mark II and Mark IV versions. This +is controlled by @code{ConTeXt-Mark-version} option. + +@defopt ConTeXt-Mark-version +This variables specifies which version of Mark should be used. Values +currently supported are @code{"II"}, the default, and @code{"IV"}. It +can be set globally using customization interface or on a per-file +basis, by specifying it as a file variable. +@end defopt + +@node Viewing +@section Viewing the Formatted Output +@cindex Viewing +@cindex Previewing +@cindex Starting a previewer + +@AUCTeX{} allows you to start external programs for previewing the +formatted output of your document. + +@menu +* Starting Viewers:: Starting viewers +* I/O Correlation:: Forward and inverse search +@end menu + +@node Starting Viewers +@subsection Starting Viewers + +Viewers are normally invoked by pressing @kbd{C-c C-c} once the document +is formatted, which will propose the @samp{View} command, or by activating the +respective entry in the Command menu. Alternatively you can type +@kbd{C-c C-v} which calls the function @code{TeX-view}. + +@deffn Command TeX-view +@kindex C-c C-v +(@kbd{C-c C-v}) Start a viewer without confirmation. The viewer is +started either on a region or the master file, depending on the last +command issued. This is especially useful for jumping to the location +corresponding to point in the viewer when using +@code{TeX-source-correlate-mode}. +@end deffn + +@AUCTeX{} will try to guess which type of viewer (@acronym{DVI}, +PostScript or @acronym{PDF}) has to be used and what options are to be +passed over to it. This decision is based on the output files present +in the working directory as well as the class and style options used in +the document. For example, if there is a @acronym{DVI} file in your +working directory, a @acronym{DVI} viewer will be invoked. In case of a +@acronym{PDF} file it will be a @acronym{PDF} viewer. If you specified +a special paper format like @samp{a5paper} or use the @samp{landscape} +option, this will be passed to the viewer by the appropriate options. +Especially some @acronym{DVI} viewers depend on this kind of information +in order to display your document correctly. In case you are using +@samp{pstricks} or @samp{psfrag} in your document, a @acronym{DVI} +viewer cannot display the contents correctly and a PostScript viewer +will be invoked instead. + +The association between the tests for the conditions mentioned above and +the viewers is made in the variable @code{TeX-view-program-selection}. +Therefore this variable is the starting point for customization if you +want to use other viewers than the ones suggested by default. + +@defopt TeX-view-program-selection +This is a list of predicates and viewers which is evaluated from front +to back in order to find out which viewer to call under the given +conditions. In the first element of each list item you can reference +one or more predicates defined in @code{TeX-view-predicate-list} or +@code{TeX-view-predicate-list-builtin}. In the second element you can +reference a viewer defined in @code{TeX-view-program-list} or +@code{TeX-view-program-list-builtin}. The viewer of the first item with +a positively evaluated predicate is selected. +@end defopt + +So @code{TeX-view-program-selection} only contains references to the +actual implementations of predicates and viewer commands respectively +which can be found elsewhere. @AUCTeX{} comes with a set of +preconfigured predicates and viewer commands which are stored in the +variables @code{TeX-view-predicate-list-builtin} and +@code{TeX-view-program-list-builtin} respectively. If you are not +satisfied with those and want to overwrite one of them or add your own +definitions, you can do so via the variables +@code{TeX-view-predicate-list} and @code{TeX-view-program-list}. + +@defopt TeX-view-predicate-list +This is a list of predicates for viewer selection and invocation. The +first element of each list item is a symbol and the second element a +Lisp form to be evaluated. The form should return nil if the predicate +is not fulfilled. + +A built-in predicate from @code{TeX-view-predicate-list-builtin} can be +overwritten by defining a new predicate with the same symbol. +@end defopt + +@defopt TeX-view-program-list +This is a list of viewer specifications each consisting of a symbolic +name and either a command line or a function to be invoked when the +viewer is called. If a command line is used, parts of it can be +conditionalized by prefixing them with predicates from +@code{TeX-view-predicate-list} or +@code{TeX-view-predicate-list-builtin}. (See the doc string for the +exact format to use.) The command line can also contain placeholders as +defined in @code{TeX-expand-list} and @code{TeX-expand-list-builtin} +which are expanded before the viewer is called. + +The third element of each item is a string, or a list of strings, with +the name of the executable, or executables, needed to open the output +file in the viewer. Placeholders defined in @code{TeX-expand-list} and +@code{TeX-expand-list-builtin} can be used here. This element is +optional and is used to check whether the viewer is actually available +on the system. + +A built-in viewer spec from @code{TeX-view-program-list-builtin} can be +overwritten by defining a new viewer spec with the same name. +@end defopt + +After the viewer is called via either the @samp{View} command or the key stroke +@kbd{C-c C-v}, the window system focus goes and stays on the viewer. If +you prefer that the focus is pulled back to Emacs immediately after that +and you are using evince-compatible viewer, customize the option +@code{TeX-view-enince-keep-focus}. + +@defopt TeX-view-evince-keep-focus +When this option is non-nil and the viewer is compatible with evince, +the focus is pulled back to Emacs immediately after the viewer is +invoked or refreshed from within @AUCTeX{}. +@end defopt + +Note that the viewer selection and invocation as described above will +only work if certain default settings in @AUCTeX{} are intact. For one, +the whole viewer selection machinery will only be triggered if there is +no @samp{%V} expander in @code{TeX-expand-list}. So if you have trouble +with the viewer invocation you might check if there is an older +customization of the variable in place. In addition, the use of a +function in @code{TeX-view-program-list} only works if the @samp{View} command +in @code{TeX-command-list} makes use of the hook +@code{TeX-run-discard-or-function}. + +@node I/O Correlation +@subsection Forward and Inverse Search +@cindex Inverse search +@cindex Forward search +@cindex I/O correlation +@cindex Source specials +@cindex Sync@TeX{} +@cindex PDFSync + +Forward and inverse search refer to the correlation between the document +source in the editor and the typeset document in the viewer. Forward +search allows you to jump to the place in the previewed document +corresponding to a certain line in the document source and inverse +search vice versa. + +@findex TeX-source-correlate-mode +@AUCTeX{} supports three methods for forward and inverse search: source +specials (only @acronym{DVI} output), the pdfsync @LaTeX{} package (only @acronym{PDF} +output) and Sync@TeX{} (any type of output). If you want to make use of +forward and inverse searching with source specials or Sync@TeX{}, switch +on @code{TeX-source-correlate-mode}. @xref{Processor Options}, on how +to do that. The use of the pdfsync package is detected automatically if +document parsing is enabled. Customize the variable +@code{TeX-source-correlate-method} to select the method to use. + +@defopt TeX-source-correlate-method +Method to use for enabling forward and inverse search. This can be +@samp{source-specials} if source specials should be used, @samp{synctex} +if Sync@TeX{} should be used, or @samp{auto} if @AUCTeX{} should decide. + +When the variable is set to @samp{auto}, @AUCTeX{} will always use +Sync@TeX{} if your @command{latex} processor supports it, source specials +otherwise. You must make sure your viewer supports the same method. + +It is also possible to specify a different method depending on the +output, either @acronym{DVI} or @acronym{PDF}, by setting the variable to an alist of the +kind +@lisp +((dvi . @samp{<source-specials or synctex>}) + (pdf . @samp{<source-specials or synctex>})) +@end lisp +in which the CDR of each entry is a symbol specifying the method to be +used in the corresponding mode. The default value of the variable is +@lisp +((dvi . source-specials) + (pdf . synctex)) +@end lisp +which is compatible with the majority of viewers. +@end defopt + +@findex TeX-view +Forward search happens automatically upon calling the viewer, e.g.@: by +typing @kbd{C-c C-v} (@code{TeX-view}). This will open the viewer or +bring it to front and display the output page corresponding to the +position of point in the source file. @AUCTeX{} will automatically pass +the necessary command line options to the viewer for this to happen. + +@vindex TeX-source-correlate-map +@findex TeX-view-mouse +You can also make special mouse event do forward search at the clicked +position. Use @code{TeX-source-correlate-map}@footnote{The keymap name is +@code{TeX-source-correlate-map}, not @code{TeX-source-correlate-mode-map}. +Actually, this keymap isn't implemented as minor mode map of +@code{TeX-source-correlate-mode}, in order that its bindings don't affect +buffers outside of @AUCTeX{}.} and @code{TeX-view-mouse} like this: +@lisp +(eval-after-load "tex" + '(define-key TeX-source-correlate-map [C-down-mouse-1] + #'TeX-view-mouse)) +@end lisp +This example binds @kbd{C-down-mouse-1}, which usually opens a concise +menu to select buffer, to the command to do forward search. + +@vindex TeX-source-correlate-start-server +Upon opening the viewer you will be asked if you want to start a server +process (Gnuserv or Emacs server) which is necessary for inverse search. +This happens only if there is no server running already. You can +customize the variable @code{TeX-source-correlate-start-server} to +inhibit the question and always or never start the server respectively. + +@defopt TeX-source-correlate-start-server +If @code{TeX-source-correlate-mode} is active and a viewer is invoked, +the default behavior is to ask if a server process should be started. +Set this variable to @code{t} if the question should be inhibited and +the server should always be started. Set it to @code{nil} if the server +should never be started. Inverse search will not be available in the +latter case. +@end defopt + +Inverse search, i.e.@: jumping to the part of your document source in +Emacs corresponding to a certain position in the viewer, is triggered +from the viewer, typically by a mouse click. Refer to the documentation +of your viewer to find out how it has to be configured and what you have +to do exactly. In xdvi you normally have to use @kbd{C-down-mouse-1}. + +@vindex TeX-source-correlate-start-server +Note that inverse search with the Evince @acronym{PDF} viewer or its MATE fork +Atril might fail in raising the Emacs frame after updating point in your +document's buffer. There is simply no way to raise the Emacs frame +reliably accross different operating systems and different window +managers with their different focus stealing policies. If the Emacs +frame is not raised after performing an inverse search from Evince or +Atril, you can customize the following option. + +@defopt TeX-raise-frame-function +A function that will be called after performing an inverse search from +Evince or Atril in order to raise the current Emacs frame. + +If your Emacs frame is already raised in that situation, just +leave this variable set to its default value +@code{raise-frame}. Otherwise, here are some alternative +settings that work for some users. + +@lisp +;; @r{Alternative 1: For some users, @t{`x-focus-frame'} works.} +(setq TeX-raise-frame-function #'x-focus-frame) + +;; @r{Alternative 2: Under GNOME 3.20 (and probably others), it} +;; @r{seems some focus stealing prevention policy prohibits that} +;; @r{some window gets the focus immediately after the user has} +;; @r{clicked in some other window. Here waiting a bit before} +;; @r{issuing the request seems to work.} +(setq TeX-raise-frame-function + (lambda () + (run-at-time 0.5 nil #'x-focus-frame))) + +;; @r{Alternative 3: Use the external @t{wmctrl} tool in order to} +;; @r{force Emacs into the focus.} +(setq TeX-raise-frame-function + (lambda () + (call-process + "wmctrl" nil nil nil "-i" "-R" + (frame-parameter (selected-frame) 'outer-window-id)))) +@end lisp +@end defopt + + +@node Debugging +@section Catching the errors +@cindex Debugging +@cindex Errors +@cindex Parsing errors +@cindex Parsing @TeX{} output +@cindex Next error +@cindex Parsing @LaTeX{} errors +@cindex Overfull boxes +@cindex Bad boxes +@cindex Underfull boxes + +Once you've formatted your document you may `debug' it, i.e.@: browse +through the errors (La)@TeX{} reported. You may also have a look at a +nicely formatted list of all errors and warnings reported by the +compiler. + +@deffn Command TeX-next-error @var{arg} @var{reparse} +@kindex C-c ` +(@kbd{C-c `}) Go to the next error reported by @TeX{}. The view will +be split in two, with the cursor placed as close as possible to the +error in the top view. In the bottom view, the error message will be +displayed along with some explanatory text. + +An optional numeric @var{arg}, positive or negative, specifies how many +error messages to move. A negative @var{arg} means to move back to +previous error messages, see also @code{TeX-previous-error}. + +The optional @var{reparse} argument makes @AUCTeX{} reparse the error +message buffer and start the debugging from the first error. This can +also be achieved by calling the function with a prefix argument +(@kbd{C-u}). +@end deffn + +@deffn Command TeX-previous-error @var{arg} +@kindex M-g p +(@kbd{M-g p}) Go to the previous error reported by @TeX{}. An optional +numeric @var{arg} specifies how many error messages to move backward. +This is like calling @code{TeX-next-error} with a negative argument. +@end deffn + +The command @code{TeX-previous-error} works only if @AUCTeX{} can parse +the whole @TeX{} log buffer. This is controlled by the +@code{TeX-parse-all-errors} variable. + +@defopt TeX-parse-all-errors +If t, @AUCTeX{} automatically parses the whole output log buffer right +after running a @TeX{} command, in order to collect all warnings and +errors. This makes it possible to navigate back and forth between the +error messages using @code{TeX-next-error} and +@code{TeX-previous-error}. This is the default. If nil, @AUCTeX{} does +not parse the whole output log buffer and @code{TeX-previous-error} +cannot be used. +@end defopt + +As default, @AUCTeX{} will display a special help buffer containing the +error reported by @TeX{} along with the documentation. There is however +an `expert' option, which allows you to display the real @TeX{} output. + +@defopt TeX-display-help +If t @AUCTeX{} will automatically display a help text whenever an error +is encountered using @code{TeX-next-error} (@kbd{C-c `}). If nil a +terse information about the error is displayed in the echo area. If +@code{expert} @AUCTeX{} will display the output buffer with the raw +@TeX{} output. +@end defopt + +@menu +* Ignoring warnings:: Controlling warnings to be reported +* Error overview:: List of all errors and warnings +@end menu + +@node Ignoring warnings +@subsection Controlling warnings to be reported + +Normally @AUCTeX{} will only report real errors, but you may as well +ask it to report `bad boxes' and warnings as well. + +@deffn Command TeX-toggle-debug-bad-boxes +@kindex C-c C-t C-b +@vindex TeX-debug-bad-boxes +(@kbd{C-c C-t C-b}) Toggle whether @AUCTeX{} should stop at bad boxes +(i.e.@: overfull and underfull boxes) as well as normal errors. The +boolean option @code{TeX-debug-bad-boxes} is set accordingly. +@end deffn + +@deffn Command TeX-toggle-debug-warnings +@kindex C-c C-t C-w +@vindex TeX-debug-warnings +(@kbd{C-c C-t C-w}) Toggle whether @AUCTeX{} should stop at warnings as +well as normal errors. The boolean option @code{TeX-debug-warnings} is +set accordingly. +@end deffn + +While many users desire to have warnings reported after compilation, +there are certain warnings that are considered unimportant and users +want to ignore them. For a more fine-grained control of what kinds of +warnings should be shown after compilation, @AUCTeX{} provides other +options. + +@defopt TeX-ignore-warnings +Controls which warnings are to be ignored. + +It can be a regexp matching the message of the warnings to be ignored. + +More advanced users can set also this option to a symbol with the name +of a custom function taking as arguments all the information of the +warning listed in @code{TeX-error-list} variable, except the last one +about whether to ignore the warning. See the code of @code{TeX-warning} +function and the documentation of @code{TeX-error-list} for more +details. +@end defopt + +@deffn Command TeX-toggle-suppress-ignored-warnings +@kindex C-c C-t C-x +@vindex TeX-suppress-ignored-warnings +(@kbd{C-c C-t C-x}) Toggle whether @AUCTeX{} should actually hide the +ignored warnings specified with @code{TeX-ignore-warnings}. The boolean +option @code{TeX-suppress-ignored-warnings} is set accordingly. If this +is nil, all warnings are shown, even those matched by +@code{TeX-ignore-warnings}, otherwise these are hidden. + +Note that @code{TeX-debug-warnings} takes the precedence: if it is nil, +all warnings are hidden in any case. +@end deffn + +@node Error overview +@subsection List of all errors and warnings + +When the option @code{TeX-parse-all-errors} is non-nil, you will be also +able to open an overview of all errors and warnings reported by the @TeX{} +compiler. + +@deffn Command TeX-error-overview +Show an overview of the errors and warnings occurred in the last @TeX{} +run. + +In this window you can visit the error on which point is by pressing +@key{RET}, and visit the next or previous issue by pressing @key{n} or +@key{p} respectively. A prefix argument to these keys specifies how +many errors to move forward or backward. You can visit an error also by +clicking on its message. Jump to error point in the source code with +@key{j}, and use @key{l} see the error in the log buffer. In addition, +you can toggle visibility of bad boxes, generic warnings, and ignored +warnings with @key{b}, @key{w}, and @key{x}, respectively (see +@ref{Ignoring warnings} for details). Press @key{q} to quit the +overview. +@end deffn + +@defopt TeX-error-overview-open-after-TeX-run +When this boolean variable is non-nil, the error overview will be +automatically opened after running @TeX{} if there are errors or warnings +to show. +@end defopt + +The error overview is opened in a new window of the current frame by +default, but you can change this behavior by customizing the option +@code{TeX-error-overview-setup}. + +@defopt TeX-error-overview-setup +Controls the frame setup of the error overview. The possible value is: +@code{separate-frame}; with a nil value the current frame is used +instead. + +The parameters of the separate frame can be set with the +@code{TeX-error-overview-frame-parameters} option. + +If the display does not support multi frame, the current frame +will be used regardless of the value of this variable. +@vindex TeX-error-overview-frame-parameters +@end defopt + +@node Checking +@section Checking for problems +@cindex Checking +@cindex @code{lacheck} +@cindex @code{chktex} +@cindex Finding errors +@cindex Running @code{lacheck} +@cindex Running @code{chktex} +@cindex Style +@cindex Problems +@cindex Flymake +@cindex Running Flymake + +Running @TeX{} or @LaTeX{} will only find regular errors in the +document, not examples of bad style. Furthermore, description of the +errors may often be confusing. The utilities @code{lacheck} and +@code{chktex} can be used to find style errors, such as forgetting to +escape the space after an abbreviation or using @samp{...} instead of +@samp{\ldots} and other similar problems. You start @code{lacheck} with +@kbd{C-c C-c Check @key{RET}} and @code{chktex} with @kbd{C-c C-c ChkTeX +@key{RET}}. The result will be a list of errors in the +@samp{*compilation*} buffer. You can go through the errors with +@kbd{C-x `} (@code{next-error}, @pxref{Compilation,,,emacs,The Emacs +Editor}), which will move point to the location of the next error. + +Alternatively, you may want in-buffer notation. @AUCTeX{} provides +support for this using the Flymake package in Emacs 26 or newer +(@pxref{Using Flymake,,,Flymake,GNU Flymake} for details). To enable, +call @kbd{M-x flymake-mode @key{RET}} in the buffer or enable it in all +buffers by adding this to your init file: +@lisp +(add-hook 'LaTeX-mode-hook #'flymake-mode) +@end lisp +Note that @AUCTeX{} currently only provides support for using +@code{chktex} as the flymake backend. + +Each of the two utilities @code{lacheck} and @code{chktex} will find +some errors the other doesn't, but @code{chktex} is more configurable, +allowing you to create your own errors. You may need to install the +programs before using them. You can get @code{lacheck} from +URL:@url{https://www.ctan.org/pkg/lacheck} and +@code{chktex} from +URL:@url{https://www.ctan.org/pkg/chktex}. @w{@TeX{} Live} contains +both. + +@node Control +@section Controlling the output +@cindex Controlling the output +@cindex Output +@cindex Redisplay output +@cindex Processes +@cindex Killing a process +@cindex Finding the master file +@cindex Master file +@cindex Stopping a process +@cindex Current file +@cindex Finding the current file + +A number of commands are available for controlling the output of an +application running under @AUCTeX{} + +@deffn Command TeX-kill-job +@kindex C-c C-k +(@kbd{C-c C-k}) Kill currently running external application. +This may be either of @TeX{}, @LaTeX{}, previewer, Bib@TeX{}, etc. +@end deffn + +@deffn Command TeX-recenter-output-buffer +@kindex C-c C-l +(@kbd{C-c C-l}) Recenter the output buffer so that the bottom line is +visible. +@end deffn + +@deffn Command TeX-home-buffer +@kindex C-c ^ +(@kbd{C-c ^}) Go to the `master' file in the document associated with +the current buffer, or if already there, to the file where the current +process was started. +@end deffn + +Additionally, output files produced by @AUCTeX{} can be placed in a +separate directory. + +@defopt TeX-output-dir +Set this option to the path of a directory where output files will be +placed. The output files include those that are produced by applications +running under @AUCTeX{}, temporary files related to region processing and +the @previewlatex{} files. If a relative path is specified, it is +interpreted as being relative to the master file in a mutlifile document. + +This is a buffer local variable and must be set separately for all +documents and all files in a multifile document. For example, + +@example +%%% Local Variables: +%%% mode: latex +%%% TeX-output-dir: "build" +%%% End: +@end example + +Alternatively, you may use @code{setq-default} to set the default value of +this option or set it as a directory local variable (@pxref{Directory +Variables,,, emacs, The Emacs Editor}). + +Note that a non-nil value of @code{TeX-output-dir} might be incompatible +with some @TeX{} commands and macros. In particular, the @LaTeX{} macro +@samp{\include} is known to not work with this option. Some @TeX{} +packages which produce intermediary files might also be incompatible. A +possible workaround for those packages is to append the value of +@code{TeX-output-dir} to the environment variables @env{TEXINPUTS} and +@env{BIBINPUTS}. +@end defopt + +@node Cleaning +@section Cleaning intermediate and output files +@cindex Cleaning + +@deffn Command TeX-clean +@vindex plain-TeX-clean-intermediate-suffixes +@vindex plain-TeX-clean-output-suffixes +@vindex LaTeX-clean-intermediate-suffixes +@vindex LaTeX-clean-output-suffixes +@vindex docTeX-clean-intermediate-suffixes +@vindex docTeX-clean-output-suffixes +@vindex Texinfo-clean-intermediate-suffixes +@vindex Texinfo-clean-output-suffixes +@vindex ConTeXt-clean-intermediate-suffixes +@vindex ConTeXt-clean-output-suffixes +@vindex AmSTeX-clean-intermediate-suffixes +@vindex AmSTeX-clean-output-suffixes +Remove generated intermediate files. In case a prefix argument is +given, remove output files as well. + +Canonical access to the function is provided by the @samp{Clean} and +@samp{Clean All} entries in @code{TeX-command-list}, invokable with +@kbd{C-c C-c} or the Command menu. + +The patterns governing which files to remove can be adapted separately +for each @AUCTeX{} mode by means of the following variables: +@itemize +@item +@code{plain-TeX-clean-intermediate-suffixes} +@item +@code{plain-TeX-clean-output-suffixes} +@item +@code{LaTeX-clean-intermediate-suffixes} +@item +@code{LaTeX-clean-output-suffixes} +@item +@code{docTeX-clean-intermediate-suffixes} +@item +@code{docTeX-clean-output-suffixes} +@item +@code{Texinfo-clean-intermediate-suffixes} +@item +@code{Texinfo-clean-output-suffixes} +@item +@code{ConTeXt-clean-intermediate-suffixes} +@item +@code{ConTeXt-clean-output-suffixes} +@item +@code{AmSTeX-clean-intermediate-suffixes} +@item +@code{AmSTeX-clean-output-suffixes} +@end itemize + +@end deffn + +@defopt TeX-clean-confirm +Control if deletion of intermediate and output files has to be confirmed +before it is actually done. If non-nil, ask before deleting files. +@end defopt + +@node Documentation +@section Documentation about macros and packages +@cindex Documentation + +@deffn Command TeX-documentation-texdoc +@kindex C-c ? +(@kbd{C-c ?}) Get documentation about the packages installed on your +system, using @command{texdoc} to find the manuals. The function will +prompt for the name of packages. If point is on a word, this will be +suggested as default. + +If the command is called with a prefix argument, you will be shown a +list of manuals of the given package among to choose. + +The command can be invoked by the key binding mentioned above as well as +the @samp{Find Documentation...} entry in the mode menu. +@end deffn + +@node Customization +@chapter Customization and Extension + +@menu +* Modes and Hooks:: Modes and Hooks +* Multifile:: Multifile Documents +* Parsing Files:: Automatic Parsing of @TeX{} Files +* Internationalization:: Language Support +* Automatic:: Automatic Customization +* Style Files:: Writing Your Own Style Support +@end menu + +@node Modes and Hooks +@section Modes and Hooks + +@AUCTeX{} supports a wide variety of derivatives and extensions of +@TeX{}. Besides plain @TeX{} those are @LaTeX{}, AMS-@TeX{}, +@ConTeXt{}, Texinfo and doc@TeX{}. For each of them there is a separate +major mode in @AUCTeX{} and each major mode runs @code{text-mode-hook}, +@code{TeX-mode-hook} as well as a hook special to the mode in this +order. (As an exception, Texinfo mode does not run @code{TeX-mode-hook}.) +The following table provides an overview of the respective mode +functions and hooks. + +@multitable {Plain @TeX{}} {@code{plain-tex-mode}} {@code{plain-TeX-mode-hook}} +@headitem Type @tab Mode function @tab Hook +@item Plain @TeX{} @tab @code{plain-tex-mode} @tab @code{plain-TeX-mode-hook} +@item @LaTeX{} @tab @code{latex-mode} @tab @code{LaTeX-mode-hook} +@item AMS-@TeX{} @tab @code{ams-tex-mode} @tab @code{AmS-TeX-mode-hook} +@item @ConTeXt{} @tab @code{context-mode} @tab @code{ConTeXt-mode-hook} +@item Texinfo @tab @code{texinfo-mode} @tab @code{Texinfo-mode-hook} +@item Doc@TeX{} @tab @code{doctex-mode} @tab @code{docTeX-mode-hook} +@end multitable +@findex plain-tex-mode +@vindex plain-TeX-mode-hook +@findex latex-mode +@vindex LaTeX-mode-hook +@findex ams-tex-mode +@vindex AmS-TeX-mode-hook +@findex context-mode +@vindex ConTeXt-mode-hook +@findex texinfo-mode +@vindex Texinfo-mode-hook +@findex doctex-mode +@vindex docTeX-mode-hook + +If you need to make a customization via a hook which is only relevant +for one of the modes listed above, put it into the respective mode hook, +if it is relevant for any @AUCTeX{} mode, add it to @code{TeX-mode-hook} +and if it is relevant for all text modes, append it to +@code{text-mode-hook}. + +Other useful hooks are listed below. + +@defvr Variable TeX-after-compilation-finished-functions +Hook which is run after the @TeX{}/@LaTeX{} processor has successfully +finished compiling your document. (@xref{Processing}, for finding out +how to compile your document.) Each function in the hook is run with +the compiled output document as its argument. + +This is useful for automatically refreshing the viewer after +re-compilation especially when using Emacs viewers such as DocView or +PDF Tools. The function @code{TeX-revert-document-buffer} can be added +to the hook for this purpose. +@end defvr +@vindex TeX-after-compilation-finished-functions +@findex TeX-revert-document-buffer + +@node Multifile +@section Multifile Documents +@cindex Multifile Documents +@cindex Documents +@cindex Documents with multiple files +@cindex Multiple Files +@cindex Many Files +@cindex Including +@cindex \include +@cindex Inputing +@cindex \input +@cindex Master file + +You may wish to spread a document over many files (as you are likely to do if +there are multiple authors, or if you have not yet discovered the power +of the outline commands (@pxref{Outline})). This can be done by having a +``master'' file in which you include the various files with the @TeX{} +macro @samp{\input} or the @LaTeX{} macro @samp{\include}. These +files may also include other files themselves. However, to format the +document you must run the commands on the top level master file. + +When you, for example, ask @AUCTeX{} to run a command on the master file, +it has no way of knowing the name of the master file. By default, +it will assume that the current file is the master file. If you insert +the following in your init file (@file{init.el} or @file{.emacs}), @AUCTeX{} will use a more +advanced algorithm. + +@lisp +(setq-default TeX-master nil) ; @r{Query for master file.} +@end lisp + +In this case, @AUCTeX{} will ask for the name of the master file +associated with the buffer. To avoid asking you again, @AUCTeX{} will +automatically insert the name of the master file as a file variable +(@pxref{File Variables,,,emacs,The Emacs Editor}). You can also insert +the file variable yourself, by putting the following text at the end of +your files. + +@example +%%% Local Variables: +%%% TeX-master: "master" +%%% End: +@end example + +You should always set this variable to the name of the top level document. If +you always use the same name for your top level documents, you can set +@code{TeX-master} in your init file such as @file{init.el} or @file{.emacs}. + +@lisp +(setq-default TeX-master "master") ; @r{All master files called @t{"master"}.} +@end lisp + +@defopt TeX-master +The master file associated with the current buffer. If the file being +edited is actually included from another file, then you can tell @AUCTeX{} +the name of the master file by setting this variable. If there are +multiple levels of nesting, specify the top level file. + +If this variable is @code{nil}, @AUCTeX{} will query you for the +name. + +If the variable is @code{t}, then @AUCTeX{} will assume the file is a master +file itself. + +If the variable is @code{shared}, then @AUCTeX{} will query for the name, +but will not change the file. + +If the variable is @code{dwim}, @AUCTeX{} will try to avoid querying by +attempting to ``do what I mean''; and then change the file. +@end defopt + +@defopt TeX-one-master +Regular expression matching ordinary @TeX{} files. + +You should set this variable to match the name of all files, for which +it is a good idea to append a @code{TeX-master} file variable entry +automatically. When @AUCTeX{} adds the name of the master file as a +file variable, it does not need to ask next time you edit the file. + +If you dislike @AUCTeX{} automatically modifying your files, you can +set this variable to @samp{"<none>"}. By default, @AUCTeX{} will modify +any file with an extension of @samp{.tex}, @samp{.texi} or @samp{.dtx}. +@end defopt + +@deffn Command TeX-master-file-ask +@kindex C-c _ +(@kbd{C-c _}) Query for the name of a master file and add the respective +File Variables (@pxref{File Variables,,,emacs,The Emacs Editor}) to the +file for setting this variable permanently. + +@AUCTeX{} will not ask for a master file when it encounters existing +files. This function shall give you the possibility to insert the +variable manually. +@end deffn + +@AUCTeX{} keeps track of macros, environments, labels, and style +files that are used in a given document. For this to work with +multifile documents, @AUCTeX{} has to have a place to put the +information about the files in the document. This is done by having an +@file{auto} subdirectory placed in the directory where your document is +located. Each time you save a file, @AUCTeX{} will write information +about the file into the @file{auto} directory. When you load a file, +@AUCTeX{} will read the information in the @file{auto} directory +about the file you loaded @emph{and the master file specified by +@code{TeX-master}}. Since the master file (perhaps indirectly) includes +all other files in the document, @AUCTeX{} will get information from +all files in the document. This means that you will get from each file, +for example, completion for all labels defined anywhere in the document. + +@AUCTeX{} will create the @file{auto} directory automatically if +@code{TeX-auto-save} is non-nil. Without it, the files in the document +will not know anything about each other, except for the name of the +master file. @xref{Automatic Local}. + +@deffn Command TeX-save-document +@kindex C-c C-d +(@kbd{C-c C-d}) Save all buffers known to belong to the current document. +@end deffn + +@defopt TeX-save-query +If non-nil, then query the user before saving each file with +@code{TeX-save-document}. +@end defopt + + +@node Parsing Files +@section Automatic Parsing of @TeX{} Files +@cindex Parsing @TeX{} +@cindex Automatic Parsing +@cindex Tabs +@cindex Tabify +@cindex Untabify + +@AUCTeX{} depends heavily on being able to extract information from the +buffers by parsing them. Since parsing the buffer can be somewhat slow, +the parsing is initially disabled. You are encouraged to enable them by +adding the following lines to your init file such as @file{init.el} or @file{.emacs}. + +@lisp +(setq TeX-parse-self t) ; @r{Enable parse on load.} +(setq TeX-auto-save t) ; @r{Enable parse on save.} +@end lisp + +The latter command will make @AUCTeX{} store the parsed information in +an @file{auto} subdirectory in the directory each time the @TeX{} files +are stored, @pxref{Automatic Local}. If @AUCTeX{} finds the pre-parsed +information when loading a file, it will not need to reparse the buffer. +The information in the @file{auto} directory is also useful for +multifile documents, @pxref{Multifile}, since it allows each file to +access the parsed information from all the other files in the document. +This is done by first reading the information from the master file, and +then recursively the information from each file stored in the master +file. + +The variables can also be set on a per file basis, by changing the file +local variables. + +@example +%%% Local Variables: +%%% TeX-parse-self: t +%%% TeX-auto-save: t +%%% End: +@end example + +Even when you have disabled the automatic parsing, you can force the +generation of style information by pressing @kbd{C-c C-n}. This is +often the best choice, as you will be able to decide when it is +necessary to reparse the file. + +@defopt TeX-parse-self +Parse file after loading it if no style hook is found for it. +@end defopt + +@defopt TeX-auto-save +Automatically save style information when saving the buffer. +@end defopt + +@deffn Command TeX-normal-mode @var{arg} +@kindex C-c C-n +(@kbd{C-c C-n}) Remove all information about this buffer, and apply the +style hooks again. Save buffer first including style information. With +optional argument, also reload the style hooks. +@end deffn + +When @AUCTeX{} saves your buffer, it can optionally convert all tabs in +your buffer into spaces. +Tabs confuse @AUCTeX{}'s error message parsing and so should generally be +avoided. However, tabs are significant in some environments, and so by +default @AUCTeX{} does not remove them. +To convert tabs to spaces when saving a buffer, insert the +following in your init file such as @file{init.el} or @file{.emacs}: + +@lisp +(setq TeX-auto-untabify t) +@end lisp + +@defopt TeX-auto-untabify +Automatically remove all tabs from a file before saving it. +@end defopt + +Instead of disabling the parsing entirely, you can also speed it +significantly up by limiting the information it will search for (and +store) when parsing the buffer. You can do this by setting the default +values for the buffer local variables @code{TeX-auto-regexp-list} and +@code{TeX-auto-parse-length} in your init file such as @file{init.el} or @file{.emacs}. + +@lisp +;; @r{Only parse LaTeX class and package information.} +(setq-default TeX-auto-regexp-list 'LaTeX-auto-minimal-regexp-list) +;; @r{The class and package information is usually near the beginning.} +(setq-default TeX-auto-parse-length 2000) +@end lisp + +This example will speed the parsing up significantly, but @AUCTeX{} +will no longer be able to provide completion for labels, macros, +environments, or bibitems specified in the document, nor will it know +what files belong to the document. + +These variables can also be specified on a per file basis, by changing +the file local variables. + +@example +%%% Local Variables: +%%% TeX-auto-regexp-list: TeX-auto-full-regexp-list +%%% TeX-auto-parse-length: 999999 +%%% End: +@end example + +@defopt TeX-auto-regexp-list +List of regular expressions used for parsing the current file. +@end defopt + +@defopt TeX-auto-parse-length +Maximal length of @TeX{} file that will be parsed. +@end defopt + +The pre-specified lists of regexps are defined below. You can use these +before loading @AUCTeX{} by quoting them, as in the example above. + +@defvr Constant TeX-auto-empty-regexp-list +Parse nothing +@end defvr + +@defvr Constant LaTeX-auto-minimal-regexp-list +Only parse @LaTeX{} class and packages. +@end defvr + +@defvr Constant LaTeX-auto-label-regexp-list +Only parse @LaTeX{} labels. +@end defvr + +@defvr Constant LaTeX-auto-index-regexp-list +Only parse @LaTeX{} index and glossary entries. +@end defvr + +@defvr Constant LaTeX-auto-class-regexp-list +Only parse macros in @LaTeX{} classes and packages. +@end defvr + +@defvr Constant LaTeX-auto-pagestyle-regexp-list +Only parse @LaTeX{} pagestyles. +@end defvr + +@defvr Constant LaTeX-auto-counter-regexp-list +Only parse @LaTeX{} counters. +@end defvr + +@defvr Constant LaTeX-auto-length-regexp-list +Only parse @LaTeX{} lengths. +@end defvr + +@defvr Constant LaTeX-auto-savebox-regexp-list +Only parse @LaTeX{} saveboxes. +@end defvr + +@defvr Constant LaTeX-auto-regexp-list +Parse common @LaTeX{} commands. +@end defvr + +@defvr Constant plain-TeX-auto-regexp-list +Parse common plain @TeX{} commands. +@end defvr + +@defvr Constant TeX-auto-full-regexp-list +Parse all @TeX{} and @LaTeX{} commands that @AUCTeX{} can use. +@end defvr + +@node Internationalization +@section Language Support +@cindex Internationalization +@cindex Language Support +@cindex CJK language +@cindex C@TeX{} +@cindex China@TeX{} +@cindex p@TeX{} +@cindex up@TeX{} +@cindex ASCII p@TeX{} +@cindex j@TeX{} +@cindex NTT j@TeX{} +@cindex k@TeX{} +@cindex H@LaTeX{} +@cindex @acronym{CJK}-@LaTeX{} + +@TeX{} and Emacs are usable for European (Latin, Cyrillic, Greek) based +languages. Some @LaTeX{} and EmacsLisp packages are available for easy +typesetting and editing documents in European languages. + +@c Some Texinfo macros are not used because they require quite recent +@c texinfo versions (2005-03-05): +@c Second arg of @acronym is available with 4.7, @comma is available in +@c 4.7, @abbr is available in 4.8. +@c -> @abbr{MULE, MULtilingual Enhancement to GNU Emacs} +@c -> @acronym{CJK, Chinese@comma{} Japanese@comma{} and Korean} + +All Emacs versions supported by current @AUCTeX{} can handle +@acronym{CJK} (Chinese, Japanese, and Korean) languages by default. + +In most cases, special versions of @TeX{} engines are needed for +high-quality typesetting of @acronym{CJK} languages: C@TeX{} and +China@TeX{} for Chinese, ASCII p@TeX{}, up@TeX{} and NTT j@TeX{} for +Japanese, H@LaTeX{} and k@TeX{} for Korean. They are necessary as well +when you want to typeset documents saved in their domestic encodings +such as @samp{Shift-JIS}. Currently, @AUCTeX{} offers native support +for p@TeX{}, up@TeX{} and j@TeX{} only. + +@c FIXME: We need more information for CTeX, ChinaTeX, KTeX, and HLaTeX. + +If you don't need fine tuning in the result with respect to the +typesetting rules of their respective national standards, most unicode +based @TeX{} engines, e.g.@: Lua@TeX{} and Xe@TeX{}, can handle +@acronym{CJK} languages by default if they are encoded in +@acronym{UTF}-8. The @acronym{CJK}-@LaTeX{} package is provided for +supporting @acronym{CJK} scripts in a standard @LaTeX{} document. + +@menu +* European:: Using @AUCTeX{} with European Languages +* Japanese:: Using @AUCTeX{} with Japanese +@end menu + +@node European +@subsection Using @AUCTeX{} with European Languages +@cindex Europe +@cindex European Characters +@cindex @acronym{ISO} Character set +@cindex @acronym{ISO} 8859 Latin 1 +@cindex Latin 1 + +@subsubsection Typing and Displaying Non-ASCII Characters + +First you will need a way to write non-ASCII characters. You can either +use macros, or teach @TeX{} about the @acronym{ISO} character sets. I prefer the +latter, it has the advantage that the usual standard emacs word +movement and case change commands will work. + +Recommended encoding for @LaTeX{} document is @acronym{UTF}-8. Recent +@LaTeX{}2e has native support for @acronym{UTF}-8. If your @LaTeX{}2e is +not recent enough, just add @samp{\usepackage[utf8]@{inputenc@}}. + +You can still use @acronym{ISO} 8859 Latin 1 encoding with +@samp{\usepackage[latin1]@{inputenc@}}. + +To be able to display non-ASCII characters you will need an appropriate +font. All Emacs versions supported by current @AUCTeX{} can display 8-bit +characters, provided that suitable fonts are installed. + +@c FIXME: These are considered as kind of obsolete, aren't they? +A compromise is to use an European character set when editing the file, +and convert to @TeX{} macros when reading and writing the files. + +@table @file +@item iso-cvt.el +@cindex @file{iso-cvt.el} +Much like @file{iso-tex.el} but is bundled with Emacs 19.23 and later. + +@item X-Symbol +@cindex X-Symbol +a much more complete package for Emacs that can also handle a lot of +mathematical characters and input methods. +@end table + +@subsubsection Style Files for Different Languages + +@cindex ispell +@AUCTeX{} supports style files for several languages. Each style file +may modify @AUCTeX{} to better support the language, and will run +a language specific hook that will allow you to for example change +ispell dictionary, or run code to change the keyboard remapping. The +following will for example choose a Danish dictionary for documents +including @samp{\usepackage[danish]@{babel@}}. +This requires parsing to be enabled, @pxref{Parsing Files}. + +@lisp +(add-hook 'TeX-language-dk-hook + (lambda () (ispell-change-dictionary "danish"))) +@end lisp + +The following style files are recognized: + +@c In alphabetic order of the hooks: +@vindex TeX-language-bg-hook +@vindex TeX-language-cz-hook +@vindex TeX-language-dk-hook +@vindex TeX-language-en-hook +@vindex TeX-language-nl-hook +@vindex TeX-language-de-hook +@vindex TeX-language-it-hook +@vindex TeX-language-is-hook +@vindex TeX-language-pl-hook +@vindex TeX-language-pt-br-hook +@vindex TeX-language-pt-hook +@vindex TeX-language-sk-hook +@vindex TeX-language-sv-hook +@cindex Brazilian Portuguese +@cindex Bulgarian +@cindex Czech +@cindex Italian +@cindex Danish +@cindex Dutch +@cindex English +@cindex German +@cindex Polish +@cindex Portuguese +@cindex Slovak +@cindex Swedish +@table @file +@item brazilian +@itemx brazil +Runs style hook @code{TeX-language-pt-br-hook}. Gives @samp{"} word +syntax, makes the @key{"} key inserts @samp{``} or @samp{''} depending on +context. Typing @key{"} twice will insert a literal @samp{"}. Typing +@key{-} twice will insert @samp{"=}, three times @samp{--}. + +@item bulgarian +Runs style hook @code{TeX-language-bg-hook}. Gives @samp{"} word syntax, +makes the @key{"} key insert a literal @samp{"}. Typing @key{"} twice +will insert @samp{"`} or @samp{"'} depending on context. Typing @key{-} +twice will insert @samp{"=}, three times @samp{--}. + +@item czech +Runs style hook @code{TeX-language-cz-hook}. Pressing @key{"} will +insert @samp{\uv@{} and @samp{@}} depending on context. + +@c FIXME: Is the difference between dk and danish really intented? +@item danish +Runs style hook @code{TeX-language-dk-hook}. Pressing @key{"} will +insert @samp{"`} and @samp{"'} depending on context. Typing @key{-} +twice will insert @samp{"=}, i.e.@: a hyphen string allowing hyphenation +in the composing words. +@c dk.sty seems to be obsolete, so we don't want to encourage using it. +@c @item dk +@c Runs style hook @code{TeX-language-dk-hook}. + +@item dutch +Runs style hook @code{TeX-language-nl-hook}. + +@item english +@itemx australian +@itemx canadian +@itemx newzealand +Runs style hook @code{TeX-language-en-hook}. + +@item frenchb +@itemx francais +Runs style hook @code{TeX-language-fr-hook}. Pressing @key{"} will +insert @samp{\og} and @samp{\fg} depending on context. Note that the +language name for customizing @code{TeX-quote-language-alist} is +@samp{french}. + +@item german +@itemx ngerman +Runs style hook @code{TeX-language-de-hook}. Gives @samp{"} word +syntax, makes the @key{"} key insert a literal @samp{"}. Pressing the +key twice will give you opening or closing German quotes (@samp{"`} or +@samp{"'}). Typing @key{-} twice will insert @samp{"=}, three times +@samp{--}. + +@item icelandic +Runs style hook @code{TeX-language-is-hook}. Gives @samp{"} word syntax, +makes the @key{"} key insert a literal @samp{"}. Typing @key{"} twice +will insert @samp{"`} or @samp{"'} depending on context. Typing @key{-} +twice will insert @samp{"=}, three times @samp{--}. + +@item italian +Runs style hook @code{TeX-language-it-hook}. Pressing @key{"} will +insert @samp{"<} and @samp{">} depending on context. + +@item polish +Runs style hook @code{TeX-language-pl-hook}. Gives @samp{"} word syntax +and makes the @key{"} key insert a literal @samp{"}. Pressing @key{"} +twice will insert @samp{"`} or @samp{"'} depending on context. + +@item polski +Runs style hook @code{TeX-language-pl-hook}. Makes the @key{"} key +insert a literal @samp{"}. Pressing @key{"} twice will insert @samp{,,} +or @samp{''} depending on context. + +@item portuguese +@itemx portuges +Runs style hook @code{TeX-language-pt-hook}. Gives @samp{"} word syntax, +makes the @key{"} key inserts @samp{"<} or @samp{">} depending on context. +Typing @key{"} twice will insert a literal @samp{"}. Typing @key{-} twice +will insert @samp{"=}, three times @samp{--}. Note that the language name +for customizing @code{TeX-quote-language-alist} is @samp{portuguese}. + +@item slovak +Runs style hook @code{TeX-language-sk-hook}. Pressing @key{"} will +insert @samp{\uv@{} and @samp{@}} depending on context. + +@item swedish +Runs style hook @code{TeX-language-sv-hook}. Pressing @key{"} will +insert @samp{''}. Typing @key{-} twice will insert @samp{"=}, three +times @samp{--}. +@end table + +Replacement of language-specific hyphen strings like @samp{"=} with +dashes does not require to type @key{-} three times in a row. You can +put point after the hypen string anytime and trigger the replacement by +typing @key{-}. + +In case you are not satisfied with the suggested behavior of quote and +hyphen insertion you can change it by customizing the variables +@code{TeX-quote-language-alist} and +@code{LaTeX-babel-hyphen-language-alist} respectively. + +@defopt TeX-quote-language-alist +Used for overriding the default language-specific quote insertion +behavior. This is an alist where each element is a list consisting of +four items. The first item is the name of the language in concern as a +string. See the list of supported languages above. The second item is +the opening quotation mark. The third item is the closing quotation +mark. Opening and closing quotation marks can be specified directly as +strings or as functions returning a string. The fourth item is a +boolean controlling quote insertion. It should be non-nil if if the +special quotes should only be used after inserting a literal @samp{"} +character first, i.e.@: on second key press. +@end defopt + +@defopt LaTeX-babel-hyphen-language-alist +Used for overriding the behavior of hyphen insertion for specific +languages. Every element in this alist is a list of three items. The +first item should specify the affected language as a string. The second +item denotes the hyphen string to be used as a string. The third item, +a boolean, controls the behavior of hyphen insertion and should be +non-nil if the special hyphen should be inserted after inserting a +literal @samp{-} character, i.e.@: on second key press. +@end defopt + +The defaults of hyphen insertion are defined by the variables +@code{LaTeX-babel-hyphen} and @code{LaTeX-babel-hyphen-after-hyphen} +respectively. + +@defopt LaTeX-babel-hyphen +String to be used when typing @key{-}. This usually is a hyphen +alternative or hyphenation aid provided by @samp{babel} and the related +language style files, like @samp{"=}, @samp{"~} or @samp{"-}. + +Set it to an empty string or nil in order to disable language-specific +hyphen insertion. +@end defopt + +@defopt LaTeX-babel-hyphen-after-hyphen +Control insertion of hyphen strings. If non-nil insert normal hyphen on +first key press and swap it with the language-specific hyphen string +specified in the variable @code{LaTeX-babel-hyphen} on second key press. +If nil do it the other way round. +@end defopt + +@node Japanese +@subsection Using @AUCTeX{} with Japanese @TeX{} +@cindex Japan +@cindex Japanese +@cindex Nippon +@cindex NTT j@TeX{} +@cindex j@TeX{} +@cindex j@LaTeX{} +@cindex ASCII p@TeX{} +@cindex p@TeX{} +@cindex p@LaTeX{} +@cindex up@TeX{} +@cindex up@LaTeX{} +@cindex @file{tex-jp.el} +@vindex TeX-default-mode +@vindex TeX-parse-self +@vindex TeX-engine +@vindex TeX-engine-alist +@vindex japanese-TeX-mode +@findex japanese-plain-tex-mode +@findex japanese-latex-mode + +To write Japanese text with @AUCTeX{}, you need the versions of +@TeX{} and Emacs that support Japanese. @AUCTeX{} supports three +Japanese @TeX{} engines by default: NTT j@TeX{}, ASCII p@TeX{} and +up@TeX{}. + +Activate @code{japanese-plain-tex-mode} or @code{japanese-latex-mode} to +use the Japanese @TeX{} engines. If it doesn't work, send mail to +Masayuki Ataka @email{masayuki.ataka@@gmail.com} or Ikumi Keita +@email{ikumikeita@@jcom.home.ne.jp}, who currently concern with stuff +related to Japanese in @AUCTeX{}. None of the primary @AUCTeX{} +maintainers understand Japanese, so they cannot help you. + +It is recommended to enable @code{TeX-parse-self} for typical Japanese +@LaTeX{} users. When enabled, @code{japanese-latex-mode} selects the +suitable Japanese @TeX{} engine automatically based on the class file +name (such as @code{jbook}, @code{jsarticle} and @code{tjreport}) and +its option. @xref{Parsing Files}. + +It is important to select the suitable Japanese @TeX{} engine because +the selected engine determines the command name such as @command{platex} +and @command{uptex} to typeset the document. If you find that wrong +command is used, check the value of @code{TeX-engine} on that buffer. +If the value does not suit the current document, change the value by the +@samp{TeXing Options} submenu below the @samp{Command} menu. +@xref{Processor Options}. + +To make the selected engine to persist across Emacs sessions, there are +two ways from which you can choose one according to your needs: + +@enumerate +@item +If you use a specific engine (almost) exclusively, customize the option +@code{japanese-TeX-engine-default}. + +@defopt japanese-TeX-engine-default +The default @code{TeX-engine} in Japanese @TeX{} mode. + +The default value is @samp{ptex}. +@end defopt +@item +If you want to set the engine on a per file basis, use the file local +variables to set @code{TeX-engine}. + +Here is a sample code to set @code{TeX-engine} to @samp{uptex}: + +@example +%%% Local Variables: +%%% mode: japanese-latex +%%% TeX-engine: uptex +%%% End: +@end example +@end enumerate + +In the both cases above, the valid value is one of @samp{ptex}, +@samp{jtex} and @samp{uptex}. + +You can override the command names associated with the above three +engines or define your own engine by customizing +@code{TeX-engine-alist}. @xref{Processor Options}. + +It is sometimes necessary to use an engine which differs from the one +@AUCTeX{} selects automatically. For example, even when you want to use +@code{j-article} document class deliberately with ASCII p@LaTeX{}, +@AUCTeX{} selects NTT j@LaTeX{} command if @code{TeX-parse-self} is +enabled, because @code{j-article} originally belongs to NTT j@LaTeX{}. +In such cases, use the file local variable method above to select the +engine you intend to use. + +If you usually use @AUCTeX{} in Japanese, setting the following +variables is useful. + +@defopt TeX-default-mode +Mode to enter for a new file when it cannot be determined whether the +file is plain @TeX{} or @LaTeX{} or what. + +If you want to enter Japanese @LaTeX{} mode whenever this may happen, +set the variable like this: +@lisp +(setq TeX-default-mode 'japanese-latex-mode) +@end lisp +@end defopt + +@defopt japanese-LaTeX-default-style +The default style/class when creating a new Japanese @LaTeX{} document. + +The default value is @samp{"jarticle"}. +@end defopt + +It is recommended also for Japanese users to customize the option +@code{TeX-PDF-from-DVI} to @samp{"Dvipdfmx"}. @xref{Processor Options}. + +There are three customize options with regard to the encoding of +Japanese text. + +@defopt japanese-TeX-use-kanji-opt-flag +If non-nil, @AUCTeX{} adds @option{-kanji} option to the typesetting +command when @code{TeX-engine} is @samp{ptex}. +@end defopt + +Usually @AUCTeX{} guesses the right coding systems for input to and +output from the Japanese @TeX{} process, but you can override them by +the following two customize options. + +@defopt TeX-japanese-process-input-coding-system +If non-nil, used for encoding input to Japanese @TeX{} process. +When @code{nil}, @AUCTeX{} tries to choose suitable coding system. +@end defopt + +@defopt TeX-japanese-process-output-coding-system +If non-nil, used for decoding output from Japanese @TeX{} process. +When @code{nil}, @AUCTeX{} tries to choose suitable coding system. +@end defopt + +The former customize options @code{japanese-TeX-command-default}, +@code{japanese-LaTeX-command-default} and +@code{japanese-TeX-command-list} are removed from @AUCTeX{}. Use +@code{japanese-TeX-engine-default} instead. If you need to customize +the executable file name such as @samp{"latex"}, the options for them, +or both, customize @code{TeX-engine-alist}. + +The following two additional font commands are available in +@LaTeX{} mode buffer. + +@table @kbd +@item C-c C-f g +@kindex C-c C-f g +@cindex @code{\textgt} +@cindex @code{\mathgt} +Insert @b{gothic font} command @samp{\textgt@{@point{}@}} or +@samp{\mathgt@{@point{}@}} depending on the context. + +@item C-c C-f m +@kindex C-c C-f m +@cindex @code{\textmc} +@cindex @code{\mathmc} +Insert mincho font command @samp{\textmc@{@point{}@}} or +@samp{\mathmc@{@point{}@}} depending on the context. + +@end table + +Although they are meaningful only with @samp{ptex} and @samp{uptex} +engines, it won't matter in buffers with other engines. + +See @file{tex-jp.el} for more information. + +@node Automatic +@section Automatic Customization +@cindex Automatic Customization +@cindex Extracting @TeX{} symbols +@cindex Automatic +@cindex @file{auto} directories. +@cindex Parsing @TeX{} +@cindex @TeX{} parsing +@cindex Generating symbols + +Since @AUCTeX{} is so highly customizable, it makes sense that it is able +to customize itself. The automatic customization consists of scanning +@TeX{} files and extracting symbols, environments, and things like that. + +The automatic customization is done on three different levels. The +global level is the level shared by all users at your site, and consists +of scanning the standard @TeX{} style files, and any extra styles added +locally for all users on the site. The private level deals with those +style files you have written for your own use, and use in different +documents. You may have a @file{~/lib/TeX/} directory where you store +useful style files for your own use. The local level is for a specific +directory, and deals with writing customization for the files for your +normal @TeX{} documents. + +If compared with the environment variable @env{TEXINPUTS}, the +global level corresponds to the directories built into @TeX{}. The +private level corresponds to the directories you add yourself, except for +@file{.}, which is the local level. + +@menu +* Automatic Global:: Automatic Customization for the Site +* Automatic Private:: Automatic Customization for a User +* Automatic Local:: Automatic Customization for a Directory +@end menu + +By default @AUCTeX{} will search for customization files in all the +global, private, and local style directories, but you can also set the +path directly. This is useful if you for example want to add another +person's style hooks to your path. Please note that all matching files +found in @code{TeX-style-path} are loaded, and all hooks defined in the +files will be executed. + +@defopt TeX-style-path +List of directories to search for @AUCTeX{} style files. +@end defopt + +By default, when @AUCTeX{} searches a directory for files, it will +recursively search through subdirectories. + +@defopt TeX-file-recurse +Whether to search @TeX{} directories recursively: nil means do not +recurse, a positive integer means go that far deep in the directory +hierarchy, t means recurse indefinitely. +@end defopt + +By default, @AUCTeX{} will ignore files named @file{.}, @file{..}, +@file{SCCS}, @file{RCS}, and @file{CVS}. + +@defopt TeX-ignore-file +Regular expression matching file names to ignore. + +These files or directories will not be considered when searching for +@TeX{} files in a directory. +@end defopt + +@node Automatic Global +@subsection Automatic Customization for the Site +@cindex Global style hook directory +@cindex Global macro directory +@cindex Site macro directory +@cindex Global @TeX{} macro directory +@cindex Site @TeX{} macro directory +@cindex Global directories +@cindex Site information + +Assuming that the automatic customization at the global level was done +when @AUCTeX{} was installed, your choice is now: will you use it? If +you use it, you will benefit by having access to all the symbols and +environments available for completion purposes. The drawback is slower +load time when you edit a new file and perhaps too many confusing +symbols when you try to do a completion. + +You can disable the automatic generated global style hooks by setting +the variable @code{TeX-auto-global} to nil. + +@defopt TeX-macro-global +Directories containing the site's @TeX{} style files. +@end defopt + +@defopt TeX-style-global +Directory containing hand generated @TeX{} information. + +These correspond to @TeX{} macros shared by all users of a site. +@end defopt + +@defopt TeX-auto-global +Directory containing automatically generated information. + +For storing automatic extracted information about the @TeX{} macros +shared by all users of a site. +@end defopt + +@node Automatic Private +@subsection Automatic Customization for a User +@cindex Private style hook directory +@cindex Private macro directory +@cindex Personal macro directory +@cindex Private @TeX{} macro directory +@cindex Personal @TeX{} macro directory +@cindex Private directories +@cindex Personal information + +You should specify where you store your private @TeX{} macros, so +@AUCTeX{} can extract their information. The extracted information will +go to the directories listed in @code{TeX-auto-private} + +Use @kbd{M-x TeX-auto-generate @key{RET}} to extract the information. + +@defopt TeX-macro-private +Directories where you store your personal @TeX{} macros. The value +defaults to the directories listed in the @env{TEXINPUTS} and +@env{BIBINPUTS} environment variables or to the respective directories +in @code{$TEXMFHOME} of @command{kpsewhich} setting if no results can be obtained from the environment +variables. +@end defopt + +@defopt TeX-auto-private +List of directories containing automatically generated @AUCTeX{} style +files. These correspond to the personal @TeX{} macros. +@end defopt + +@deffn Command TeX-auto-generate @var{tex} @var{auto} +(@kbd{M-x TeX-auto-generate @key{RET}}) Generate style hook for +@var{tex} and store it in @var{auto}. If @var{tex} is a directory, +generate style hooks for all files in the directory. +@end deffn + +@defopt TeX-style-private +List of directories containing hand generated @AUCTeX{} style files. +These correspond to the personal @TeX{} macros. +@end defopt + +@node Automatic Local +@subsection Automatic Customization for a Directory +@cindex Local style hooks +@cindex Updating style hooks +@cindex Automatic updating style hooks +@cindex Local style hooks +@cindex Local style directory + +@AUCTeX{} can update the style information about a file each time you +save it, and it will do this if the directory @code{TeX-auto-local} +exists. @code{TeX-auto-local} is by default set to @samp{"auto"}, so +simply creating an @file{auto} directory will enable automatic saving of +style information. + +The advantage of doing this is that macros, labels, etc.@: defined in any +file in a multifile document will be known in all the files in the +document. The disadvantage is that saving will be slower. To disable, +set @code{TeX-auto-local} to nil. + +@defopt TeX-style-local +Directory containing hand generated @TeX{} information. + +These correspond to @TeX{} macros found in the current directory. +@end defopt + +@defopt TeX-auto-local +Directory containing automatically generated @TeX{} information. + +These correspond to @TeX{} macros found in the current directory. +@end defopt + +@node Style Files +@section Writing Your Own Style Support +@cindex Style files +@cindex Style hooks +@cindex @file{style} + +@xref{Automatic}, for a discussion about automatically generated global, +private, and local style files. The hand generated style files are +equivalent, except that they by default are found in @file{style} +directories instead of @file{auto} directories. + +@menu +* Simple Style:: A Simple Style File +* Adding Macros:: Adding Support for Macros +* Adding Environments:: Adding Support for Environments +* Adding Other:: Adding or Examining Other Information +* Hacking the Parser:: Automatic Extraction of New Things +@end menu + +If you write some useful support for a public @TeX{} style file, please +send it to us. + +@node Simple Style +@subsection A Simple Style File +@cindex @file{book.el} +@cindex Sample style file +@cindex Style file +@cindex Example of a style file. +@cindex Style hook +@cindex Adding a style hook + +Here is a simple example of a style file. + +@lisp +;;; book.el - Special code for book style. + +(TeX-add-style-hook + "book" + (lambda () + (LaTeX-largest-level-set "part")) + TeX-dialect) +@end lisp + +The example is from the @AUCTeX{} sources and is loaded for any @LaTeX{} +document using the book document class (or style before @LaTeX{}2e). +(Note that the above code is much simplified for explanatory purpose.) +The file specifies that the largest kind of section in such a document +is @samp{part}. The interesting thing to notice is that the style file +defines an (anonymous) function, and adds it to the list of loaded style +hooks by calling @code{TeX-add-style-hook}. + +The first time the user indirectly tries to access some style-specific +information, such as the largest sectioning command available, the style +hooks for all files directly or indirectly read by the current document +are executed. The actual files will only be evaluated once, but the +hooks will be called for each buffer using the style file. + +Note that the basename of the style file and the name of the style hook +should usually be identical. + +@defun TeX-add-style-hook @var{style} @var{hook} &optional @var{dialect-expr} +Add @var{hook} to the list of functions to run when we use the @TeX{} +file @var{style} and the current dialect is one in the set derived from +@var{dialect-expr}. When @var{dialect-expr} is omitted, then @var{hook} +is allowed to be run whatever the current dialect is. + +@var{dialect-expr} may be one of: + +@itemize +@item +A symbol indicating a singleton containing one basic @TeX{} dialect, +this symbol shall be selected among: +@table @code +@item :latex +For all files in @LaTeX{} mode, or any mode derived thereof. +@item :bibtex +For all files in Bib@TeX{} mode, or any mode derived thereof. +@item :texinfo +For all files in Texinfo mode. +@item :plain-tex +For all files in plain-@TeX{} mode, or any mode derived thereof. +@item :context +For all files in @ConTeXt{} mode. +@item :classopt +For class options of @LaTeX{} document. This is provided as +pseudo-dialect for style hooks associated with class options. +@end table +@item +A logical expression like: +@table @code +@item (or @var{dialect-expression1} @dots{} @var{dialect-expression_@var{n}}) +For union of the sets of dialects corresponding to @var{dialect-expression1} +through @var{dialect-expression_@var{n}} +@item (and @var{dialect-expression1} @dots{} @var{dialect-expression_@var{n}}) +For intersection of the sets of dialects corresponding to +@var{dialect-expression1} through @var{dialect-expression_@var{n}} +@item (nor @var{dialect-expression1} @dots{} @var{dialect-expression_@var{n}}) +For complement of the union sets of dialects corresponding to +@var{dialect-expression1} through @var{dialect-expression_@var{n}} +relatively to the set of all supported dialects +@item (not @var{dialect-expr}) +For complement set of dialect corresponding to @var{dialect-expr} +relatively to the set of all supported dialects +@end table +@end itemize + +@end defun + +In case of adding a style hook for @LaTeX{}, when calling function +@code{TeX-add-style-hook} it is thought more futureproof for argument +@var{dialect-expr} to pass constant @code{TeX-dialect} currently +defined to @code{:latex}, rather than passing @code{:latex} directly. + +@defvr Constant TeX-dialect +Default dialect for use with function @code{TeX-add-style-hook} for +argument @var{dialect-expr} when the hook is to be run only on @LaTeX{} +file, or any mode derived thereof. +@end defvr + + +@node Adding Macros +@subsection Adding Support for Macros +@cindex Adding macros +@cindex Macros, adding +@cindex Defining macros in style hooks + +The most common thing to define in a style hook is new symbols (@TeX{} +macros). Most likely along with a description of the arguments to the +function, since the symbol itself can be defined automatically. + +Here are a few examples from @file{latex.el}. + +@lisp +(TeX-add-style-hook + "latex" + (lambda () + (TeX-add-symbols + '("arabic" TeX-arg-counter) + '("label" TeX-arg-define-label) + '("ref" TeX-arg-ref) + '("newcommand" TeX-arg-define-macro [ "Number of arguments" ] t) + '("newtheorem" TeX-arg-define-environment + [ TeX-arg-environment "Numbered like" ] + t [ TeX-arg-counter "Within counter" ])))) +@end lisp + +@defun TeX-add-symbols @var{symbol} @dots{} +Add each @var{symbol} to the list of known symbols. +@end defun + +Each argument to @code{TeX-add-symbols} is a list describing one symbol. +The head of the list is the name of the symbol, the remaining elements +describe each argument. + +If there are no additional elements, the symbol will be inserted with +point inside braces. Otherwise, each argument of this function should +match an argument of the @TeX{} macro. What is done depends on the argument +type. + +If a macro is defined multiple times, @AUCTeX{} will choose the one with +the longest definition (i.e.@: the one with the most arguments). + +Thus, to overwrite +@example + '("tref" 1) ; @r{one argument} +@end example +you can specify +@example + '("tref" TeX-arg-ref ignore) ; @r{two arguments} +@end example + +@code{ignore} is a function that does not do anything, so when you +insert a @samp{tref} you will be prompted for a label and no more. + +You can use the following types of specifiers for arguments: + +@table @code +@item string +Use the string as a prompt to prompt for the argument. + +@item number +Insert that many braces, leave point inside the first. 0 and -1 are +special. 0 means that no braces are inserted. -1 means that braces are +inserted around the macro and an active region (e.g.@: @samp{@{\tiny +foo@}}). If there is no active region, no braces are inserted. + +@item nil +Insert empty braces. + +@item t +Insert empty braces, leave point between the braces. + +@item other symbols +Call the symbol as a function. You can define your +own hook, or use one of the predefined argument hooks. + +@item list +If the car is a string, insert it as a prompt and the next +element as initial input. Otherwise, call the car of the list with +the remaining elements as arguments. + +@item vector +Optional argument. If it has more than one element, parse it +as a list, otherwise parse the only element as above. Use square +brackets instead of curly braces, and is not inserted on empty user +input. +@end table + +A lot of argument hooks have already been defined. The first argument to +all hooks is a flag indicating if it is an optional argument. It is up +to the hook to determine what to do with the remaining arguments, if +any. Typically the next argument is used to overwrite the default +prompt. + +@ftable @code +@item TeX-arg-conditional +Implements if @var{expr} @var{then} @var{else}. If @var{expr} evaluates +to true, parse @var{then} as an argument list, else parse @var{else} as an +argument list. + +@item TeX-arg-literal +Insert its arguments into the buffer. Used for specifying extra syntax +for a macro. + +@item TeX-arg-free +Parse its arguments but use no braces when they are inserted. + +@item TeX-arg-eval +Evaluate arguments and insert the result in the buffer. + +@item TeX-arg-label +Prompt for a label completing with known labels. If Ref@TeX{} is +active, prompt for the reference format. + +@item TeX-arg-ref +Prompt for a label completing with known labels. If Ref@TeX{} is +active, do not prompt for the reference format. Usually, reference +macros should use this function instead of @code{TeX-arg-label}. + +@item TeX-arg-index-tag +Prompt for an index tag. This is the name of an index, not the entry. + +@item TeX-arg-index +Prompt for an index entry completing with known entries. + +@item TeX-arg-length +Prompt for a @LaTeX{} length completing with known lengths. + +@item TeX-arg-macro +Prompt for a @TeX{} macro with completion. + +@item TeX-arg-date +@vindex TeX-date-format +Prompt for a date, defaulting to the current date. The format of the +date is specified by the @code{TeX-date-format} option. If you want to +change the format when the @samp{babel} package is loaded with a +specific language, set @code{TeX-date-format} inside the appropriate +language hook (for details @pxref{European}). + +@item TeX-arg-version +Prompt for the version of a file, using as initial input the current +date. + +@item TeX-arg-environment +Prompt for a @LaTeX{} environment with completion. + +@item TeX-arg-cite +@vindex TeX-arg-cite-note-p +Prompt for a Bib@TeX{} citation. If the variable +@code{TeX-arg-cite-note-p} is non-nil, ask also for optional note in citations. + +@item TeX-arg-counter +Prompt for a @LaTeX{} counter completing with known counters. + +@item TeX-arg-savebox +Prompt for a @LaTeX{} savebox completing with known saveboxes. + +@item TeX-arg-file +Prompt for a filename in the current directory, and use it with the +extension. + +@item TeX-arg-file-name +Prompt for a filename and use as initial input the name of the file +being visited in the current buffer, with extension. + +@item TeX-arg-file-name-sans-extension +Prompt for a filename and use as initial input the name of the file +being visited in the current buffer, without extension. + +@item TeX-arg-input-file +@vindex TeX-arg-input-file-search +Prompt for the name of an input file in @TeX{}'s search path, and use it +without the extension. Run the style hooks for the file. (Note that +the behavior (type of prompt and inserted file name) of the function can +be controlled by the variable @code{TeX-arg-input-file-search}.) + +@item TeX-arg-define-label +Prompt for a label completing with known labels. Add label to list of +defined labels. + +@item TeX-arg-define-length +Prompt for a @LaTeX{} length completing with known lengths. Add length +to list of defined lengths. + +@item TeX-arg-define-macro +Prompt for a @TeX{} macro with completion. Add macro to list of defined +macros. + +@item TeX-arg-define-environment +Prompt for a @LaTeX{} environment with completion. Add environment to +list of defined environments. + +@item TeX-arg-define-cite +Prompt for a Bib@TeX{} citation. + +@item TeX-arg-define-counter +Prompt for a @LaTeX{} counter. + +@item TeX-arg-define-savebox +Prompt for a @LaTeX{} savebox. + +@item TeX-arg-document +@vindex LaTeX-default-style +@vindex LaTeX-default-options +@vindex TeX-arg-input-file-search +@vindex LaTeX-style-list +Prompt for a @LaTeX{} document class, using @code{LaTeX-default-style} +as default value and @code{LaTeX-default-options} as default list of +options. If the variable @code{TeX-arg-input-file-search} is t, you +will be able to complete with all @LaTeX{} classes available on your +system, otherwise classes listed in the variable @code{LaTeX-style-list} +will be used for completion. It is also provided completion for options +of many common classes. + +@item LaTeX-arg-usepackage +@vindex TeX-arg-input-file-search +Prompt for @LaTeX{} packages. If the variable +@code{TeX-arg-input-file-search} is t, you will be able to complete with +all @LaTeX{} packages available on your system. It is also provided +completion for options of many common packages. + +@item TeX-arg-bibstyle +Prompt for a Bib@TeX{} style file completing with all style available on +your system. + +@item TeX-arg-bibliography +Prompt for Bib@TeX{} database files completing with all databases available +on your system. + +@item TeX-arg-corner +Prompt for a @LaTeX{} side or corner position with completion. + +@item TeX-arg-lr +Prompt for a @LaTeX{} side with completion. + +@item TeX-arg-tb +Prompt for a @LaTeX{} side with completion. + +@item TeX-arg-pagestyle +Prompt for a @LaTeX{} pagestyle with completion. + +@item TeX-arg-verb +Prompt for delimiter and text. + +@item TeX-arg-verb-delim-or-brace +Prompt for delimiter and text. This function is similar to +@code{TeX-arg-verb}, but is intended for macros which take their +argument enclosed in delimiters or in braces. + +@item TeX-arg-pair +Insert a pair of numbers, use arguments for prompt. The numbers are +surrounded by parentheses and separated with a comma. + +@item TeX-arg-size +Insert width and height as a pair. No arguments. + +@item TeX-arg-coordinate +Insert x and y coordinates as a pair. No arguments. + +@item LaTeX-arg-author +@vindex LaTeX-default-author +Prompt for document author, using @code{LaTeX-default-author} as initial +input. + +@item TeX-read-hook +Prompt for a @LaTeX{} hook and return it. + +@item TeX-arg-hook +Prompt for a @LaTeX{} hook and insert it as a @TeX{} macro argument. + +@item TeX-read-key-val +Prompt for a @samp{key=value} list of options and return them. + +@item TeX-arg-key-val +Prompt for a @samp{key=value} list of options and insert it as a @TeX{} +macro argument. +@end ftable + +If you add new hooks, you can assume that point is placed directly after +the previous argument, or after the macro name if this is the first +argument. Please leave point located after the argument you are +inserting. If you want point to be located somewhere else after all +hooks have been processed, set the value of @code{TeX-exit-mark}. It +will point nowhere, until the argument hook sets it. + +Some packages provide macros that are rarely useful to non-expert users. +Those should be marked as expert macros using +@code{TeX-declare-expert-macros}. + +@defun TeX-declare-expert-macros @var{style} @var{macros}... +Declare @var{macros} as expert macros of @var{style}. + +Expert macros are completed depending on @code{TeX-complete-expert-commands}. +@end defun + + +@node Adding Environments +@subsection Adding Support for Environments +@cindex Adding environments +@cindex Environments, adding +@cindex Defining environments in style hooks + +Adding support for environments is very much like adding support for +@TeX{} macros, except that each environment normally only takes one +argument, an environment hook. The example is again a short version of +@file{latex.el}. + +@lisp +(TeX-add-style-hook + "latex" + (lambda () + (LaTeX-add-environments + '("document" LaTeX-env-document) + '("enumerate" LaTeX-env-item) + '("itemize" LaTeX-env-item) + '("list" LaTeX-env-list)))) +@end lisp + +It is completely up to the environment hook to insert the environment, +but the function @code{LaTeX-insert-environment} may be of some help. +The hook will be called with the name of the environment as its first +argument, and extra arguments can be provided by adding them to a list +after the hook. + +For simple environments with arguments, for example defined with +@samp{\newenvironment}, you can make @AUCTeX{} prompt for the arguments +by giving the prompt strings in the call to +@code{LaTeX-add-environments}. The fact that an argument is optional +can be indicated by wrapping the prompt string in a vector. + +For example, if you have defined a @code{loop} environment with the +three arguments @var{from}, @var{to}, and @var{step}, you can add +support for them in a style file. + +@example +%% loop.sty + +\newenvironment@{loop@}[3]@{...@}@{...@} +@end example + +@lisp +;; loop.el + +(TeX-add-style-hook + "loop" + (lambda () + (LaTeX-add-environments + '("loop" "From" "To" "Step")))) +@end lisp + +If an environment is defined multiple times, @AUCTeX{} will choose the +one with the longest definition. Thus, if you have an enumerate style +file, and want it to replace the standard @LaTeX{} enumerate hook above, +you could define an @file{enumerate.el} file as follows, and place it in +the appropriate style directory. + +@lisp +(TeX-add-style-hook + "latex" + (lambda () + (LaTeX-add-environments + '("enumerate" LaTeX-env-enumerate foo)))) + +(defun LaTeX-env-enumerate (environment &optional _ignore) ...) +@end lisp + +The symbol @code{foo} will be passed to @code{LaTeX-env-enumerate} as +the second argument, but since we only added it to overwrite the +definition in @file{latex.el} it is just ignored. + +@defun LaTeX-add-environments @var{env} @dots{} +Add each @var{env} to list of loaded environments. +@end defun + +@defun LaTeX-insert-environment @var{env} [ @var{extra} ] +Insert environment of type @var{env}, with optional argument @var{extra}. +@end defun + +Following is a list of available hooks for +@code{LaTeX-add-environments}: + +@ftable @code +@item LaTeX-env-item +Insert the given environment and the first item. + +@item LaTeX-env-figure +Insert the given figure-like environment with a caption and a label. + +@item LaTeX-env-array +Insert the given array-like environment with position and column +specifications. + +@item LaTeX-env-label +Insert the given environment with a label. + +@item LaTeX-env-list +Insert the given list-like environment, a specifier for the label and +the first item. + +@item LaTeX-env-minipage +Insert the given minipage-like environment with position and width +specifications. + +@item LaTeX-env-tabular* +Insert the given tabular*-like environment with width, position and +column specifications. + +@item LaTeX-env-picture +Insert the given environment with width and height specifications. + +@item LaTeX-env-bib +Insert the given environment with a label for a bibitem. + +@item LaTeX-env-contents +Insert the given environment with a filename as its argument. + +@item LaTeX-env-args +Insert the given environment with arguments. You can use this as a hook +in case you want to specify multiple complex arguments just like in +elements of @code{TeX-add-symbols}. This is most useful if the +specification of arguments to be prompted for with strings and strings +wrapped in a vector as described above is too limited. + +Here is an example from @file{listings.el} which calls a function with +one argument in order to prompt for a @samp{key=value} list to be inserted as +an optional argument of the @samp{lstlisting} environment: + +@lisp +(LaTeX-add-environments + '("lstlisting" LaTeX-env-args + [TeX-arg-key-val LaTeX-listings-key-val-options])) +@end lisp +@end ftable + +Some packages provide environments that are rarely useful to non-expert +users. Those should be marked as expert environments using +@code{LaTeX-declare-expert-environments}. + +@defun LaTeX-declare-expert-environments @var{style} @var{environments}... +Declare @var{environments} as expert environments of @var{style}. + +Expert environments are completed depending on @code{TeX-complete-expert-commands}. +@end defun + + +@node Adding Other +@subsection Adding or Examining Other Information +@cindex Adding bibliographies +@cindex Bibliographies, adding +@cindex Examining package/class options +@cindex package/class options, Examining +@cindex Adding support for completion of package/class options +@cindex support for completion of package/class options, Adding +@cindex Viewer predicates +@cindex Defining bibliographies in style hooks +@cindex Adding labels +@cindex Labels, adding +@cindex Defining labels in style hooks +@cindex Adding other information +@cindex Other information, adding +@cindex Defining other information in style hooks + +@subsubsection Adding bibliographies in style hooks + +You can also specify bibliographical databases and labels in the style +file. This is probably of little use, since this information will +usually be automatically generated from the @TeX{} file anyway. + +@defun LaTeX-add-bibliographies @var{bibliography} @dots{} +Add each @var{bibliography} to list of loaded bibliographies. +@end defun + +@defun LaTeX-add-labels @var{label} @dots{} +Add each @var{label} to the list of known labels. +@end defun + +@subsubsection Examining Package/Class Options + +In @LaTeX{} documents, style hooks can find the package names and those +options given as optional argument(s) of @samp{\usepackage} in +@code{LaTeX-provided-package-options}. + +@defvar LaTeX-provided-package-options +Buffer local variable holding alist of options provided to @LaTeX{} +packages. Each element is a cons cell @code{(@var{package} +. @var{option-list})}. For example, its value will be +@lisp + (("babel" . ("german")) + ("geometry" . ("a4paper" "top=2cm" "left=2.5cm" "right=2.5cm")) + ...) +@end lisp +@end defvar + +You can examine whether there is a specific package-option pair by +@code{LaTeX-provided-package-options-member}. + +@defun LaTeX-provided-package-options-member @var{package} @var{option} +Return non-@code{nil} if @var{option} has been given to @var{package}. +The value is actually the tail of the list of options given to +@var{package}. +@end defun + +There are similar facilities for class names and those options given in +@code{\documentclass} declaration. + +@defvar LaTeX-provided-class-options +Buffer local variable holding alist of options provided to @LaTeX{} +classes. Each element is a cons cell @code{(@var{class} +. @var{option-list})}. For example, its value will be +@lisp + (("book" . ("a4paper" "11pt" "openany" "fleqn")) + ...) +@end lisp +@end defvar + +@defun LaTeX-provided-class-options-member @var{class} @var{option} +Return non-@code{nil} if @var{option} has been given to @var{class}. The +value is actually the tail of the list of options given to @var{class}. +@end defun + +@defun LaTeX-match-class-option @var{regexp} +Check if a documentclass option matching @var{regexp} is active. Return +first found class option matching @var{regexp}, or nil if not found. +@end defun + +These functions are also useful to implement customized predicate(s) in +@code{TeX-view-predicate-list}. @xref{Starting Viewers}. + +@subsubsection Adding Support for Option Completion +When the user inserts @samp{\usepackage} by @kbd{C-c C-m}, @AUCTeX{} asks +for the optional arguments after the package name is given. The style +file of that package can provide completion support for the optional +arguments. + +@defvar LaTeX-@var{packagename}-package-options +List of optional arguments available for the package. +@end defvar + +Here is an excerption from @samp{acronym.el}: +@lisp +(defvar LaTeX-acronym-package-options + '("footnote" "nohyperlinks" "printonlyused" "withpage" + "smaller" "dua" "nolist") + "Package options for the acronym package.") +@end lisp + +When the package accepts key-value style optional arguments, more +sophisticated completion support is needed. The package style file can +provide dynamic completion support by custom elisp function. + +@defun LaTeX-@var{packagename}-package-options +This function should ask the user for optional arguments and return them +as a string, instead of built-in option query facility. When this function +is defined, @AUCTeX{} calls it with no argument. +@end defun + +Here is an excerption from @samp{acro.el}: +@lisp +(defun LaTeX-acro-package-options () + "Prompt for package options for the acro package." + (TeX-read-key-val t LaTeX-acro-package-options-list)) +@end lisp + +As you can see in the above example, a utility function +@code{TeX-read-key-val} is available to read key-value pair(s) from users. + +Note that @code{defvar} or @code{defun} of +@code{LaTeX-@var{packagename}-package-options} should be at the top level +of the style file and not inside the style hook, because the style hook is +not yet called when the user inputs the optional arguments in response to +@kbd{C-c C-m}. + +There are similar facilities for class options. When the user inserts +@samp{\documentclass} by @kbd{C-c C-e}, the respective class style file +can provide completion support for the optional arguments. + +@defvar LaTeX-@var{classname}-class-options +List of optional arguments available for the class. +@end defvar + +@defun LaTeX-@var{classname}-class-options +Which see. +@end defun + +@node Hacking the Parser +@subsection Automatic Extraction of New Things +@cindex Parsing new macros +@cindex @file{macro.tex} +@cindex @file{macro.el} +@cindex Changing the parser + +The automatic @TeX{} information extractor works by searching for +regular expressions in the @TeX{} files, and storing the matched +information. You can add support for new constructs to the parser, +something that is needed when you add new commands to define symbols. + +For example, in the file @file{macro.tex} I define the following macro. + +@example +\newcommand@{\newmacro@}[5]@{% +\def#1@{#3\index@{#4@@#5~cite@{#4@}@}\nocite@{#4@}@}% +\def#2@{#5\index@{#4@@#5~cite@{#4@}@}\nocite@{#4@}@}% +@} +@end example + +@AUCTeX{} will automatically figure out that @samp{newmacro} is a macro +that takes five arguments. However, it is not smart enough to +automatically see that each time we use the macro, two new macros are +defined. We can specify this information in a style hook file. + +@lisp +;;; macro.el --- Special code for my own macro file. + +;;; Code: + +(defvar TeX-newmacro-regexp + '("\\\\newmacro@{\\\\\\([a-zA-Z]+\\)@}@{\\\\\\([a-zA-Z]+\\)@}" + (1 2) TeX-auto-multi) + "Matches \\newmacro definitions.") + +(defvar TeX-auto-multi nil + "Temporary for parsing \\newmacro definitions.") + +(defun TeX-macro-cleanup () + "Move symbols from `TeX-auto-multi' to `TeX-auto-symbol'." + (mapc (lambda (list) + (mapc (lambda (symbol) + (setq TeX-auto-symbol + (cons symbol TeX-auto-symbol))) + list)) + TeX-auto-multi)) + +(defun TeX-macro-prepare () + "Clear `Tex-auto-multi' before use." + (setq TeX-auto-multi nil)) + +(add-hook 'TeX-auto-prepare-hook #'TeX-macro-prepare) +(add-hook 'TeX-auto-cleanup-hook #'TeX-macro-cleanup) + +(TeX-add-style-hook + "macro" + (lambda () + (TeX-auto-add-regexp TeX-newmacro-regexp) + (TeX-add-symbols '("newmacro" + TeX-arg-macro + (TeX-arg-macro "Capitalized macro: \\") + t + "BibTeX entry: " + nil)))) + +;;; macro.el ends here +@end lisp + +When this file is first loaded, it adds a new entry to +@code{TeX-newmacro-regexp}, and defines a function to be called before +the parsing starts, and one to be called after the parsing is done. It +also declares a variable to contain the data collected during parsing. +Finally, it adds a style hook which describes the @samp{newmacro} macro, +as we have seen it before. + +So the general strategy is: Add a new entry to @code{TeX-newmacro-regexp}. +Declare a variable to contain intermediate data during parsing. Add hook +to be called before and after parsing. In this case, the hook before +parsing just initializes the variable, and the hook after parsing +collects the data from the variable, and adds them to the list of symbols +found. + +@defvar TeX-auto-regexp-list +List of regular expressions matching @TeX{} macro definitions. + +The list has the following format ((@var{regexp} @var{match} @var{table}) @dots{}), that +is, each entry is a list with three elements. + +@var{regexp}. Regular expression matching the macro we want to parse. + +@var{match}. A number or list of numbers, each representing one +parenthesized subexpression matched by @var{regexp}. + +@var{table}. The symbol table to store the data. This can be a function, in +which case the function is called with the argument @var{match}. Use +@code{TeX-match-buffer} to get match data. If it is not a function, it +is presumed to be the name of a variable containing a list of match +data. The matched data (a string if @var{match} is a number, a list of +strings if @var{match} is a list of numbers) is put in front of the table. +@end defvar + +@defvar TeX-auto-prepare-hook nil +List of functions to be called before parsing a @TeX{} file. +@end defvar + +@defvar TeX-auto-cleanup-hook nil +List of functions to be called after parsing a @TeX{} file. +@end defvar + +@node Appendices +@appendix Copying, Changes, Development, FAQ, Texinfo Mode + +@menu +* Copying this Manual:: +* Changes:: +* Development:: +* FAQ:: +* Texinfo mode:: +@end menu + +@node Copying this Manual +@appendixsec Copying this Manual + +@ifinfo +The copyright notice for this manual is: + +@insertcopying +@end ifinfo + +The full license text can be read here: + +@menu +* GNU Free Documentation License:: License for copying this manual. +@end menu + +@lowersections +@include fdl.texi +@raisesections + +@node Changes +@appendixsec Changes and New Features + +@lowersections +@include changes.texi +@raisesections + +@subheading Older versions +See the file @file{history.texi} for older changes. + +@node Development +@appendixsec Future Development + +@lowersections +@include todo.texi +@raisesections + +@node FAQ +@appendixsec Frequently Asked Questions + +@lowersections +@include faq.texi +@raisesections + +@node Texinfo mode +@appendixsec Features specific to @AUCTeX{}'s Texinfo major mode + +@AUCTeX{} includes a major mode for editting Texinfo files. This major +mode is not the same mode as the native Texinfo mode (@pxref{Texinfo Mode,,, +texinfo,Texinfo}) of Emacs, although they have the same name. However, +@AUCTeX{} still relies on a number of functions from the native Texinfo +mode. + +The following text describes which functionality is offered by @AUCTeX{} +and which by the native Texinfo mode. This should enable you to decide +when to consult the @AUCTeX{} manual and when the manual of the native +mode. And in case you are a seasoned user of the native mode, the +information should help you to swiftly get to know the +@AUCTeX{}-specific commands. + +@menu +* Exploiting:: How @AUCTeX{} and the native mode work together +* Superseding:: Where the native mode is superseded +* Mapping:: Where key bindings are mapped to the native mode +* Unbinding:: Which native mode key bindings are missing +@end menu + +@node Exploiting +@appendixsubsec How @AUCTeX{} and the native mode work together + +In a nutshell the split between @AUCTeX{} Texinfo mode, and native +Texinfo mode is as follows: + +@itemize +@item +Most of the editing (environment creation, commenting, font command +insertions) and/or processing commands (e.g.@: compiling or printing) +which are available in other @AUCTeX{} modes are also handled by +@AUCTeX{} in Texinfo mode. + +@item +Texinfo-related features (e.g.@: info node linkage or menu creation) rely +on the commands provided by the native Texinfo mode. @AUCTeX{} provides +the key bindings to reach these functions, keeping the same keys as in +native Texinfo whenever possible, or similar ones otherwise. +@end itemize + +@node Superseding +@appendixsubsec Where the native mode is superseded + +This section is directed to users of the native Texinfo mode switching +to @AUCTeX{}. It follows the summary of the native mode +(@pxref{Texinfo Mode Summary,,,texinfo,Texinfo}) and lists which of its commands +are no longer of use. + +@table @asis +@item Insert commands +In the native Texinfo mode, frequently used Texinfo commands can be +inserted with key bindings of the form @kbd{C-c C-c @var{k}} where +@var{k} differs for each Texinfo command; @kbd{c} inserts @code{@@code}, +@kbd{d} inserts @code{@@dfn}, @kbd{k} @code{@@kbd}, etc. + +In @AUCTeX{} commands are inserted with the key binding @kbd{C-c C-m} +instead which prompts for the macro to be inserted. For font selection +commands (like @code{@@b}, @code{@@i}, or @code{@@emph}) and a few related ones (like @code{@@var}, +@code{@@key} or @code{@@code}) there are bindings which insert the respective macros +directly. They have the form @kbd{C-c C-f @var{k}} or @kbd{C-c C-f +C-@var{k}} and call the function @code{TeX-font}. Type @kbd{C-c C-f +@key{RET}} to get a list of supported commands. + +Note that the prefix argument is not handled the same way by @AUCTeX{}. +Note also that the node insertion command from the native mode +(@code{texinfo-insert-@@node}) can still accessed from the Texinfo menu +in @AUCTeX{}. + +@item Insert braces +In @AUCTeX{} braces can be inserted with the same key binding as in the +native Texinfo mode: @kbd{C-c @{}. But @AUCTeX{} uses its own function +for the feature: @code{TeX-insert-braces}. + +@item Insert environments +The native Texinfo mode does not insert full environments. Instead, it +provides the function @code{texinfo-insert-@@end} (mapped to @kbd{C-c +C-c e}) for closing an open environment with a matching @code{@@end} statement. + +In @AUCTeX{} you can insert full environments, i.e.@: both the opening and +closing statements, with the function @code{Texinfo-environment} (mapped +to @kbd{C-c C-e}). + +@item Format info files with makeinfo and @TeX{} +In the native Texinfo mode there are various functions and bindings to +format a region or the whole buffer for info or to typeset the +respective text. For example, there is @code{makeinfo-buffer} (mapped +to @kbd{C-c C-m C-b}) which runs @samp{makeinfo} on the buffer or there +is @code{texinfo-tex-buffer} (mapped to @kbd{C-c C-t C-b}) which runs +@TeX{} on the buffer in order to produce a @acronym{DVI} file. + +In @AUCTeX{} different commands for formatting or typesetting can be +invoked through the function @code{TeX-command-master} (mapped to +@kbd{C-c C-c}). After typing @kbd{C-c C-c}, you can select the desired +command, e.g @samp{Makeinfo} or @samp{TeX}, through a prompt in the mini +buffer. Note that you can make, say @samp{Makeinfo}, the default by +adding this statement in your init file: + +@lisp +(add-hook 'Texinfo-mode-hook + (lambda () (setq TeX-command-default "Makeinfo"))) +@end lisp + +Note also that @kbd{C-c C-c Makeinfo @key{RET}} is not completely +functionally equivalent to @code{makeinfo-buffer} as the latter will +display the resulting info file in Emacs, showing the node corresponding +to the position in the source file, just after a successful compilation. +This is why, while using @AUCTeX{}, invoking @code{makeinfo-buffer} +might still be more convenient. + +Note also that in the case of a multifile document, @kbd{C-c C-c} in +@AUCTeX{} will work on the whole document (provided that the file +variable @code{TeX-master} is set correctly), while +@code{makeinfo-buffer} in the native mode will process only the current +buffer, provided at the @code{@@setfilename} statement is provided. + +@item Produce indexes and print +The native Texinfo mode provides the binding @kbd{C-c C-t C-i} +(@code{texinfo-texindex}) for producing an index and the bindings +@kbd{C-c C-t C-p} (@code{texinfo-tex-print}) and @kbd{C-c C-t C-q} +(@code{tex-show-print-queue}) for printing and showing the printer +queue. These are superseded by the respective commands available +through @kbd{C-c C-c} (@code{TeX-command-master}) in @AUCTeX{}: @samp{Texindex}, +@samp{Print}, and @samp{Queue}. + +@item Kill jobs +The command @kbd{C-c C-t C-k} (@code{tex-kill-job}) in the native mode +is superseded by @kbd{C-c C-k} (@code{TeX-kill-job}) in @AUCTeX{}. +@end table + +@node Mapping +@appendixsubsec Where key bindings are mapped to the native mode + +This node follows the native Texinfo mode summary (@pxref{Texinfo Mode +Summary,,,texinfo,Texinfo}) and lists only those commands to which @AUCTeX{} +provides a keybinding. + +Basically all commands of the native mode related to producing menus and +interlinking nodes are mapped to same or similar keys in @AUCTeX{}, +while a few insertion commands are mapped to @AUCTeX{}-like keys. + +@table @asis + +@item @code{@@item} insertion +The binding @kbd{C-c C-c i} for the insertion of @code{@@item} in the +native mode is mapped to @kbd{M-@key{RET}} or @kbd{C-c C-j} in +@AUCTeX{}, similar to other @AUCTeX{} modes. + +@item @code{@@end} insertion +The binding @kbd{C-c C-c e} for closing a @code{@@@var{foo}} command by +a corresponding @code{@@end @var{foo}} statement in the native mode is +mapped to @kbd{C-c ]} in @AUCTeX{}, similar to other @AUCTeX{} modes. + +@item Move out of balanced braces +The binding @kbd{C-c @}} (@code{up-list}) is available both in the native +mode and in @AUCTeX{}. (This is because the command is not implemented +in either mode but a native Emacs command.) However, in @AUCTeX{}, you +cannot use @kbd{C-c ]} for this, as it is used for @code{@@end} insertion. + +@item Update pointers +The bindings @kbd{C-c C-u C-n} (@code{texinfo-update-node}) and @kbd{C-c +C-u C-e} (@code{texinfo-every-node-update}) from the native mode are +available in @AUCTeX{} as well. + +@item Update menus +The bindings @kbd{C-c C-u m} (@code{texinfo-master-menu}), @kbd{C-c C-u +C-m} (@code{texinfo-make-menu}), and @kbd{C-c C-u C-a} +(@code{texinfo-all-menus-update}) from the native mode are available in +@AUCTeX{} as well. The command @code{texinfo-start-menu-description}, +bound to @kbd{C-c C-c C-d} in the native mode, is bound to @kbd{C-c C-u +C-d} in @AUCTeX{} instead. +@end table + +@node Unbinding +@appendixsubsec Which native mode key bindings are missing + +The following commands from the native commands might still be useful +when working with @AUCTeX{}, however, they are not accessible with a +key binding any longer. + +@table @asis +@item @code{@@node} insertion +The node insertion command, mapped to @kbd{C-c C-c n} in the native +mode, is not mapped to any key in @AUCTeX{}. You can still access it +through the Texinfo menu, though. Another alternative is to use the +@kbd{C-c C-m} binding for macro insertion in @AUCTeX{}. + +@item Show the section structure +The command @code{texinfo-show-structure} (@kbd{C-c C-s}) from the +native mode does not have a key binding in @AUCTeX{}. The binding is +used by @AUCTeX{} for sectioning. +@end table + +@node Indices +@unnumbered Indices + +@menu +* Key Index:: +* Function Index:: +* Variable Index:: +* Concept Index:: +@end menu + +@node Key Index +@unnumberedsec Key Index + +@printindex ky + +@node Function Index +@unnumberedsec Function Index + +@printindex fn + +@node Variable Index +@unnumberedsec Variable Index + +@printindex vr + +@node Concept Index +@unnumberedsec Concept Index + +@printindex cp + +@bye + +@c Local Variables: +@c mode: texinfo +@c coding: utf-8 +@c TeX-master: t +@c End: |