diff options
Diffstat (limited to 'elpa/auctex-13.1.3/doc')
| -rw-r--r-- | elpa/auctex-13.1.3/doc/auctex.texi | 6200 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/changes.texi | 1694 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/copying.texi | 48 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/faq.texi | 158 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/fdl.texi | 506 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/history.texi | 1918 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/install.texi | 628 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/intro.texi | 106 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/macros.texi | 89 | ||||
| -rwxr-xr-x | elpa/auctex-13.1.3/doc/preview-dtxdoc.pl | 156 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/preview-faq.texi | 306 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/preview-latex.texi | 849 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/preview-problems.texi | 196 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/preview-readme.texi | 229 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/preview-todo.texi | 118 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/quickstart.texi | 327 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/tex-ref.tex | 683 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/todo.texi | 311 | ||||
| -rw-r--r-- | elpa/auctex-13.1.3/doc/wininstall.texi | 358 |
19 files changed, 14880 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: diff --git a/elpa/auctex-13.1.3/doc/changes.texi b/elpa/auctex-13.1.3/doc/changes.texi new file mode 100644 index 0000000..b8c70ba --- /dev/null +++ b/elpa/auctex-13.1.3/doc/changes.texi @@ -0,0 +1,1694 @@ +@c This is part of the AUCTeX manual. +@c Copyright (C) 1994-2002, 2004-2010, 2012-2022 Free Software +@c Foundation, Inc. +@c See file auctex.texi for copying conditions. +@include macros.texi +@ifset rawfile +@chapheading Changes and New Features in @AUCTeX{} + +@end ifset + +@heading News since last release + +@itemize @bullet +@item +@AUCTeX{} now requires GNU Emacs 25.1 or higher. + +@item +@AUCTeX{} tracks the change in Emacs where initial inputs in the +minibuffer during queries are getting phased out. Queries for the +mandatory arguments of macros and environments are adjusted where +applicable. The value which will be used after hitting @kbd{RET} without +other input is shown in the prompt in parentheses prefixed with +@samp{default}. For this change the signature of the function +@code{TeX-arg-length} is altered. The old argument list was: +@lisp +(defun TeX-arg-length (optional &optional prompt + initial-input definition default) +@end lisp + +whereas the new one is: +@lisp +(defun TeX-arg-length (optional &optional prompt + default initial-input definition) +@end lisp + +Note the position change of @code{DEFAULT}. + +@item +Indenting of conditionals is improved. Code inside constructs like +@samp{\ifx . \else . \fi} is correctly indented. An interface for style +files is also introduced which can add their macros to the indentation +engine. Check the file @file{algpseudocode.el} for an example. + +@item +You can optionally enable indent inside square brackets @samp{[]} by new +user options @code{TeX-indent-open-delimiters} and +@code{TeX-indent-close-delimiters}. +@ifclear rawfile +@xref{Indenting}. +@end ifclear + +@item +Now @file{tex-buf.el} is merged into @file{tex.el} and no longer exists. +If your personal code has @code{(require 'tex-buf)}, one of the following +prescriptions would serve. +@enumerate +@item +Remove @code{(require 'tex-buf)}. +@item +Replace it with @code{(require 'tex)}. +@item +Replace it with @code{(require 'latex)}. +@end enumerate + +@end itemize + +@heading News in 13.1 + +@itemize @bullet +@item +In math environments @samp{gather}, @samp{gather*}, @samp{gathered}, +@samp{multline} and @samp{multline*}, fill commands such as @kbd{M-q} and +@kbd{C-c C-q C-e} are disabled. This sorts out the inconsistency between +those and @samp{equation}, @samp{displaymath} environments, in latter of +which filling is already disabled. + +If you want filling in such environments, customize +@code{LaTeX-indent-environment-list} to remove them. + +Auto fill continues to work in such environment anyway. + +In addition, @AUCTeX{} adds support of alignment at @samp{&} sign in +@samp{align}-like environments such as @samp{alignat}, @samp{aligned} and +so on, as well as @samp{matrix}-like environments such as @samp{pmatrix}, +@samp{bmatrix} and so on. + +@item +Now two commands @samp{Texindex} and @samp{Texi2dvi} are available when +you type @kbd{C-c C-c} in Texinfo mode. The command @samp{Texindex} runs +@command{texindex} on index files and @samp{Texi2dvi} runs +@command{pdftexi2dvi} or @command{texi2dvi} according to the value of +@code{TeX-PDF-mode}. + +So you can typeset Texinfo documents into @acronym{PDF} or @acronym{DVI} +format from within @AUCTeX{}. + +@item +@AUCTeX{}'s own help messages for @LaTeX{} errors are now shown only for +@LaTeX{} runs. @AUCTeX{} shows raw error/warning messages found in +@file{.log} files for runs of formats other than @LaTeX{}, such as plain +@TeX{}, @ConTeXt{} and Texinfo, as it does even for @LaTeX{} runs when it +can't find a matching entry in its own help message catalogue. + +Due to this change, customize option @code{TeX-error-description-list} can +no longer have a fallback entry that matches any error. If your +customized value includes such entry, typically @samp{(".*" . "No help +available")}, please remove it. + +@item +Two functions @code{TeX-split-string} and @code{TeX-assoc} are now +obsolete and will be removed in future release. If your personal code +uses these functions, use @code{split-string} and @code{assoc-string} +instead. + +@item +The function @code{TeX-read-key-val} now accepts a function call as second +argument. This change should help @AUCTeX{} style writers who use +@code{TeX-arg-key-val} and have to deal with dynamic key-values. Example +of usage: +@lisp +(TeX-add-style-hook "foo" + (lambda () + (TeX-add-symbols + '("bar" (TeX-arg-key-val (function-returning-key-val)))))) +@end lisp + +@item +Since @AUCTeX{} 12.2, @kbd{C-x C-w} accidentally disabled the parse on +save in that buffer, even when you enabled @code{TeX-auto-save} option. +This bug was fixed. + +@item +@AUCTeX{} now requires GNU Emacs 24.3 or higher. + +@item +Old implementations for viewers were discarded, as announced long before. +The variables @code{TeX-output-view-style} and @code{TeX-view-style} have +no effect now. The former placeholders @samp{%v} and @samp{%vv} in +@code{TeX-command-list} are ignored. + +@item +@AUCTeX{} now uses lexical binding which has been introduced in Emacs +24. This change should have no user-visible effect and require no +manual adaptions except in the following cases. + +@itemize @minus +@item +Entries added to the customization variable @code{TeX-expand-list} also +had access to variables @code{command} and @code{pos}. Those are now +properly declared and named @code{TeX-expand-command} and +@code{TeX-expand-pos}. + +@item +Entries added to the customization variable @code{TeX-expand-list} had +access to a variable @code{file} which was bound to +@code{TeX-active-master}, i.e., it evaluated to either the master or +region file. This usage must be replaced with either +@code{TeX-active-master} or @code{TeX-active-master-with-quotes}. + +@item +Viewer entries in @code{TeX-view-program-list} also had access to a +variable @code{file} which was bound to the name of the master or region +file without extension. Instead, the function @code{TeX-active-master} +has to be used now. + +@item +Macro argument parsing functions could set a variable @code{exit-mark} +to the buffer position where point should be left after all arguments +have been read. This variable is now named @code{TeX-exit-mark}. + +@item +The functions in @code{LaTeX-section-hook} had access or modified the +previously undeclared variables @code{title}, @code{name}, @code{level}, +@code{done-mark}, and @code{toc}. These variables are now properly +declared and have the @samp{LaTeX-} prefix, e.g., +@code{LaTeX-done-mark}. + +@item +The functions in @code{ConTeXt-numbered-section-hook} and +@code{ConTeXt-unnumbered-section-hook} had access or modified the +previously undeclared variables @code{title}, @code{name}, @code{level}, +@code{done-mark}, and @code{reference}. These variables are now +properly declared and have the @samp{ConTeXt-} prefix, e.g., +@code{ConTeXt-title}. + +@item +The functions in @code{TeX-translate-location-hook} could access and +modify the free variables @code{file}, @code{line}, @code{error}, +@code{offset}, @code{context}, and @code{string}. Those are now properly +declared variables with the prefix @samp{TeX-translate-location-}, e.g., +@code{TeX-translate-location-file}. +@end itemize + +@item +The constant @code{LaTeX-dialect} has been renamed to @code{TeX-dialect} +and moved from @file{latex.el} to @file{tex.el}. @code{LaTeX-dialect} +now is an obsolete alias. + +@item +The style @file{latexinfo.el} is removed from @AUCTeX{}. +@file{latexinfo.el} was meant to support latexinfo which in return was a +@LaTeX{}-2.09 extension of Texinfo, but didn't manage to replace Texinfo. + +@item +The style @file{siunitx.el} is updated to support package version 3. +Key-value options provided by older package versions are removed, +deprecated macros and units are not supported anymore. + +@item +@AUCTeX{} has preliminary support for @LaTeX{}-hooks. Hooks provided by +@LaTeX{} kernel are known and available for completion in +@samp{\AddToHook}, @samp{\RemoveFromHook} and @samp{\AddToHookNext}. + +@item +@AUCTeX{} is now able to place all generated output files, including those +that are produced by applications running under @AUCTeX{}, temporary files +related to region processing and @previewlatex{} files, in an output +directory. To use this feature, set the new user option +@code{TeX-output-dir} to the absolute path of the output directory or a +relative path which would be interpreted as being relative to the master +file in a multifile document. + +Note that this feature doesn't work if the document includes sub file +placed in sub directory below the main file via @samp{\include} command. + +@item +Many other bugs were fixed. +@end itemize + +@heading News in 12.3 + +@itemize @bullet +@item +Support for @samp{PSTricks} is now @acronym{PDF}-oriented. @AUCTeX{} no +longer turns off PDF mode for @samp{PSTricks} documents even without +@samp{pst-pdf}. It now sets up @code{TeX-PDF-from-DVI} option so that +@acronym{PDF} output is generated when @code{TeX-PDF-mode} is enabled +(default). Users who want @acronym{DVI} output should disable PDF mode +explicitly by file local variable, or customize @code{TeX-PDF-mode} to +@code{nil}. + +@item +The function @code{font-latex-update-font-lock} has been obsoleted in +order to fix @samp{bug#37945}. That function was used by several style +files in order to refresh fontification after adding new symbols or +verbatim constructs. It is better to call @code{font-lock-flush} in the +former case and @code{font-latex-set-syntactic-keywords} in the latter +case. The function @code{font-latex-update-font-lock} still exists as a +no-op which only shows a warning explaining how to update font-lock as +mentioned above. + +@item +Math expression highlighting was improved. Highlighting for documents +with a lot of inline math expressions @samp{$...$} won't get scrambled +now (@samp{bug#33139}). + +In addition, it is no longer recommended to customize +@code{font-latex-math-environments}. Use @code{texmathp-tex-commands} +instead. +@ifclear rawfile +@xref{Fontification of math}. +@end ifclear + +@item +@AUCTeX{} tracks changes in @LaTeX{}2e 2020-02-02 release. @AUCTeX{} +supports the improvements to @LaTeX{} font selection mechanism (NFSS). +New macros like @samp{\textsw} or @samp{\textulc} are added to font +insertion keyboard commands. +@ifset rawfile +See the section for inserting font specifiers for details. +@end ifset +@ifclear rawfile +@xref{Font Specifiers}, for details. +@end ifclear +Further, the entries in the menu @samp{LaTeX}, @samp{Insert Font} are reorganized and +adjusted accordingly. + +Macros previously provided by @file{textcomp.sty} are now part of +@LaTeX{} kernel. @AUCTeX{} tracks this change as well and support for +the new macro @samp{\legacyoldstylenums} is added. + +@item +Insertion of environments in @LaTeX{} documents (i.e.@: @kbd{C-c C-e}) was +improved. The former code had a few bugs, which sometimes resulted in +either spurious empty line or spurious comment prefix, or both, +especially when the region is active. Those bugs are now fixed. + +@item +More bugs fixed, other minor features implemented. +@end itemize + +@heading News in 12.2 + +@itemize @bullet +@item +@AUCTeX{} reflects the changes in @LaTeX{}2e 2019-10-01 release. +@samp{filecontents} environment now takes an optional argument and can +be used anywhere in a document. The macros @samp{\Ref} and +@samp{\labelformat} are moved from @file{varioref.sty} to @LaTeX{} +kernel. @samp{amsmath} has a new macro @samp{\overunderset}. + +@item +A new method is implemented in @previewlatex{} to adjust the foreground +colors of generated images to those of Emacs, when the @LaTeX{} command +produces @acronym{PDF}. The traditional method became invalid because +of the change introduced in Ghostscript 9.27. Unfortunately, the new +method doesn't work due to a bug in Ghostscript 9.27 and is valid only +for Ghostscript > 9.27. There is also a fallback method for gs 9.27 +users which displays plain ``black on white'' images. For successful +function of @previewlatex{}, the users are encouraged to set up the new +user option @code{preview-pdf-color-adjust-method} to choose appropriate +option among the three: new, traditional and fallback method. + +@item +@AUCTeX{} has support for the Flymake package in Emacs 26 or newer. To +enable, call @kbd{M-x flymake-mode @key{RET}} or add this to your +@file{.emacs} file: +@lisp +(add-hook 'LaTeX-mode-hook #'flymake-mode) +@end lisp + +@item +The way the option @code{TeX-record-buffer} is used was corrected. It +was used in just the opposite way as the document says. Erase the +customization if you have customized this option since it now acts in +reverse to your expectation. + +@item +A former customize option @code{japanese-TeX-command-list} is removed. +Use @code{japanese-TeX-engine-default}, or if it's really necessary, +customize @code{TeX-command-list} directly if the task which the option +used to carry is required. + +@item +Support for standard @LaTeX{} without e-@TeX{} extension is now very +limited. It doesn't work if raw @TeX{} code is put on the command line +to invoke @command{latex} command. It also fails for region compilation (@kbd{C-c +C-r} and so on) with documents of non-ascii file name. In addition, it +no longer works with @previewlatex{}. We consider this incompatibility +is permissible because e-@TeX{} extension is enabled for standard +@LaTeX{} by default long ago. @LaTeX{} variants such as Xe@LaTeX{} and +Lua@LaTeX{} are not affected. + +@item +Key binds in Texinfo mode are improved. Typing @kbd{$}, @kbd{^}, +@kbd{_} and @kbd{\} now just self-inserts without pointless side effects +in Texinfo mode. + +In addition, the option @code{TeX-electric-escape} is now effective in +Texinfo mode. When it is enabled, typing @kbd{@@} will invoke +@code{TeX-electric-macro} offering completion in similar style with +other @TeX{} modes of @AUCTeX{}. + +@item +Fontification support for @samp{biblatex} package is improved and +updated to macros provided by package version 3.12. For qualified +lists, at least 2 mandatory arguments are fontified. + +@item +Support for column specifiers @samp{w} and @samp{W} provided by +@samp{array} package is added to @file{array.el}. The correct counting +of columns only works when the @samp{align} parameter is enclosed in +braces, e.g., @samp{w@{l@}@{3cm@}}. The short version @samp{wl@{3cm@}} +is not supported. + +@item +Entries for @samp{PDF Tools} are added in +@code{TeX-view-program-list-builtin} for Windows and macOS. This viewer +can be configured under these operating systems with an entry like this +in an init file: +@lisp +(setq TeX-view-program-selection '((output-pdf "PDF Tools"))) +@end lisp + +@item +Several other bugs were fixed, many minor features were added. +@end itemize + +@heading News in 12.1 + +@itemize @bullet +@item +@AUCTeX{} now requires GNU Emacs 24 or higher. Support for XEmacs has +been dropped. + +@item +Besides the change in the supported version of Emacs, there has been no +functional change in this release, which is equivalent to version 11.92. +@end itemize + +@heading News in 11.92 + +@itemize @bullet +@item +@previewlatex{} is compatible with Ghostscript 9.22 where the operator +@samp{.runandhide} is removed. All occurrences of @samp{.runandhide} in +@previewlatex{} are replaced by alternative code making it work with +Ghostscript 9.22 again. + +@item +@AUCTeX{} has a new customize option +@code{TeX-math-input-method-off-regexp}. When you begin to input a math +formula, the current input method is turned off if its name matches this +regular expression. + +In fact this variable was introduced long before, but has not been +documented in info files nor turned into a customize option with +@code{defcustom} until this release. + +@item +The window system focus is pulled back to Emacs when viewing with +evince-compatible viewers if a new customize option +@code{TeX-view-evince-keep-focus} is non-nil. + +@item +The usual dose of bug fixes was administered. +@end itemize + +@heading News in 11.91 + +@itemize @bullet +@item +Now @AUCTeX{} has a logo. The @LaTeX{} code to create it is available +in the @file{etc/} directory of the package. + +@item +Add support for @command{upmendex}, an extension of @command{makeindex} +capable of sorting indexes by unicode based ICU. + +@item +Fix @previewlatex{} to interact correctly with Japanese @LaTeX{}. The +parsing routine was made robust not to be confused by the 7-bit encoding +of Japanese text and the necessary option to @LaTeX{} command is kept +even when preamble caching is enabled. + +@item +The new ``Glossaries'' entry in @code{TeX-command-list} runs the command +@command{makeglossaries}. + +@item +Fontification of control symbols has been improved. Characters defined +in @code{font-latex-match-simple-exclude-list} do not receive any +fontification. In Doc@TeX{} mode, the character @samp{_} is removed +from @code{font-latex-match-simple-exclude-list} in order to fontify +macros like @samp{\__module_foo:nnn} correctly. + +@item +Fontification of math environments has been improved. Optional and/or +mandatory argument(s) to environments are not fontified. + +@item +@file{preview.sty} loads @file{luatex85.sty} if possible and should be +compatible with newer lua@TeX{} versions. + +@item +@AUCTeX{} has a new customize option @code{TeX-ispell-verb-delimiters}. +This string contains usual characters used as delimiters for in-line +verbatim macros like @samp{\verb}. Text between delimiters after an +in-line verbatim macro will be skipped during spell checking. + +@item +Fontification of in-line verbatim macros has been improved. +@file{font-latex.el} recognizes an optional or a mandatory argument for +macros like @samp{\Verb} from @file{fancyvrb.sty}, @samp{\mint} and +@samp{\mintinline} from @file{minted.sty} and fontifies verbatim content +correctly. + +@item +@AUCTeX{} can put and parse labels in optional argument of environments. +Inserting labels is done by new function +@code{LaTeX-env-label-as-keyval}. A new customize option +@code{LaTeX-listing-label} is available as prefix to labels in code +typesetting environments, e.g.@: @samp{lstlisting} environment provided by +@samp{listings} package. @code{LaTeX-listing-label} defaults to +@code{lst:}. Parsing of labels for later referencing relies on two +requirements: +@enumerate +@item +Label should come as last key-value argument, and +@item +label must be enclosed in braces, e.g. +@example +\begin@{lstlisting@}[caption=Some Caption,label=@{lst:foo@}] +... +\end@{lstlisting@} +@end example +@end enumerate + +@item +The function @code{LaTeX-label} now takes a second optional argument +@code{NO-INSERT}. When non-@code{nil}, @code{LaTeX-label} reads a label +and returns it as a string. This argument is also passed to any +function bound to @code{LaTeX-label-function} (see next item). + +@item +@strong{Incompatible change:} The signature for the function passed with +the customize option @code{LaTeX-label-function} has changed. The +function bound to this variable is now expected to take an optional +second argument @code{NO-INSERT}. When this argument is non-@code{nil}, +the function should read and only return a label as a string; insertion +is done by another function. + +@item +Directory local variables were ineffective for +@code{japanese-latex-mode} and @code{japanese-plain-tex-mode}. This bug +was fixed. (This was actually done in @AUCTeX{} 11.90, but not +advertised) + +@item +The output of Japanese text from Japanese @TeX{} engines is decoded +correctly for most cases, according to the encoding of the @TeX{} +documents and the locale. The difference between MS Windows, macOS and +unix-like OS is taken into account. (This was actually done in +@AUCTeX{} 11.90, but not advertised) + +@item +Quite a few new @LaTeX{} packages are supported. + +@item +As usual, many bugs were fixed. + +@end itemize + +@heading News in 11.90 + +@itemize @bullet +@item +In addition to the completion performed by @code{TeX-complete-symbol}, +@AUCTeX{} now also supports the new Emacs standard completion-at-point +facility (see the Emacs command @code{completion-at-point}). This also +means that modern completion UIs like @i{company-mode} work out of the +box in @TeX{} and @LaTeX{} buffers. +@ifclear rawfile +@xref{Completion}, for details. +@end ifclear + +@item +Completion is now aware of being inside a math environment and then +completes math macros. + +@item +@AUCTeX{} is able to display several levels of super- and subscripts, +each one raised above and a bit smaller than its basis. For this +feature, have a look at the customize options +@code{font-latex-fontify-script} (especially the new values +@code{multi-level} and @code{invisible}) and +@code{font-latex-fontify-script-max-level}. Also, the script characters +@samp{^} and @samp{_} are also fontified with a special face named +@code{font-latex-script-char-face}. +@ifclear rawfile +@xref{Fontification of math}, for details. +@end ifclear + +@item +Parsing of format specification in various tabular environments has been +improved. The function @code{LaTeX-insert-item} (@kbd{C-c @key{LFD}}) +inserts suitable number of ampersands for @samp{*@{num@}@{cols@}} +constructs. Style files for @LaTeX{} packages @samp{tabularx}, +@samp{tabulary}, @samp{longtable}, @samp{dcolumn} and @samp{siunitx} are +adapted to take advantage of this improvement. + +@item +@AUCTeX{} has a new Ispell dictionary @file{tex-ispell.el} for macros +and environments which will be skipped during spell checking. The +activiation of this feature is controlled by a new customize option +@code{TeX-ispell-extend-skip-list}, which is set to @code{t} and +activated by default. + +@item +@AUCTeX{} has a new customize option @code{TeX-raise-frame-function} +that is currently only used by Evince and Atril inverse search to raise +the Emacs frame. + +@item +When inserting a new float, @AUCTeX{} will now prompt for a +short-caption if the length of the caption provided is greater than a +certain size. This size is controlled via a new user option +@code{LaTeX-short-caption-prompt-length}. + +@item +Parsing of the compilation log has been reworked. You should encounter +fewer mistaken files while navigating through errors and warnings. + +@item +Two new user options, @code{TeX-ignore-warnings} and +@code{TeX-suppress-ignored-warnings}, allow ignoring certain warnings +after compilation of the document. +@ifclear rawfile +@xref{Ignoring warnings}, for details. +@end ifclear + +@item +A new option, @code{TeX-PDF-from-DVI}, controls if and how to produce a +@acronym{PDF} file by converting a @acronym{DVI} file. This supersedes +@code{TeX-PDF-via-dvips-ps2pdf} which is still recognized but marked as +obsolete and may be removed in future releases. + +@item +Support for a number of external viewers has been added: +@itemize +@item +Atril viewer. Forward and inverse search requires version 1.9.1 or +later to work. + +@item +dviout viewer on Windows. Note that this setup works when +@code{TeX-source-correlate-method} is set to use @samp{source-specials} +for @acronym{DVI}, e.g.: +@lisp +(setq TeX-source-correlate-method + '((dvi . source-specials) + (pdf . synctex))) +@end lisp +which is the default. + +@item +SumatraPDF viewer on Windows. + +@item +Zathura viewer. Forward and inverse search requires a recent version of +the program to work (3.4 or later). +@end itemize + +@item +A new function, @code{TeX-documentation-texdoc}, for reading +documentation with @samp{texdoc} has been added. @code{TeX-doc} is +still available but now @kbd{C-c ?} runs +@code{TeX-documentation-texdoc}. + +@item +@AUCTeX{} has a new custom option +@code{LaTeX-reftex-cite-format-auto-activate} which controls the +automatic activation of citation formats provided by Ref@TeX{} when a style +file is loaded and Ref@TeX{} is enabled. Currently, @file{biblatex.el}, +@file{harvard.el}, @file{jurabib.el} and @file{natbib.el} use this +feature. If you have customized @code{reftex-cite-format} and want to +use your settings, you should set this variable to @code{nil}. + +@item +@AUCTeX{} now has limited support for the TikZ package. For the moment, +this includes some basic support for prompting the user of arguments to +the @samp{\draw} macro. + +@item +The style @file{graphicx.el} went through a bigger overhaul. The +optional argument of command @samp{\includegraphics} now supports +key-val query; keys can independently be chosen anytime by pressing the +@key{,} key. As a side effect, the variable +@code{LaTeX-includegraphics-options-alist} is now no-op and is removed +from @file{tex-style.el}. You can safely remove any customization of it +from your init file. The mandatory argument of @samp{\includegraphics} +knows about image file extensions supported by the used engine and +offers them for inclusion. + +@item +Support for other @LaTeX{} packages was improved, and style files for +several new packages were added. + +@item +Many bugs were crushed along the way. +@end itemize + +@heading News in 11.89 + +@itemize @bullet +@item +You can now run all commands needed to compile a document and then open +the viewer with a single command: @code{TeX-command-run-all}, bound to +@kbd{C-c C-a}. + +@item +Commands such as @samp{LaTeX} and @samp{View} can now be executed conveniently on the +current section (or part, chapter, subsection, etc). See +@code{LaTeX-command-section} and +@code{LaTeX-command-section-change-level}. +@ifclear rawfile +@xref{Starting a Command}, for details. +@end ifclear + +@item +Forward and backward search with Evince now also work when only a region +of the document is compiled/viewed. + +@item +To open the PDF output file you can now use also PDF Tools, a document +viewer for Emacs. With it, as a plus, forward and backward search is +accurate at word level. + +@item +With new option @code{TeX-PDF-via-dvips-ps2pdf} it is possible to +compile a document to @acronym{DVI} and then convert it to @acronym{PDF} +using @command{dvips}--@command{ps2pdf} before viewing it. + +@item +New option @code{TeX-file-line-error} allows to select file:line:error +style for error messages. + +@item +Indent @samp{\[...\]} math mode as a regular environment by default. + +@item +Now @AUCTeX{} suggests to run @command{makeindex} when appropriate. + +@item +@code{TeX-view-program-list} can contain, as third optional element of +each item, the name of the executable(s) needed to open the viewer. + +@item +@code{TeX-expand-list} variable has been split into +@code{TeX-expand-list} and @code{TeX-expand-list-builtin}. Only the +former is intended to be customized by the user, the latter contains +built-in expanders. You might want to keep in @code{TeX-expand-list} +only new expansion strings. + +@item +Before running commands like @TeX{} and @LaTeX{}, now @AUCTeX{} performs +some checks. If @code{TeX-check-TeX} is non-nil, it will test whether a +working @TeX{} distribution is actually present in the system and +available to Emacs. Instead, when @code{TeX-check-engine} is non-nil, +before running @LaTeX{} commands @AUCTeX{} will check whether the +correct engine has been set, based upon known restrictions posed by +@LaTeX{} packages. + +@item +Basic support to @ConTeXt{} Mark IV has been added. Users can now +select the Mark version to be used with new option +@code{ConTeXt-Mark-version}, and @AUCTeX{} is able to catch error +messages in the output log of a Mark IV document. + +@item +Support for tons of @LaTeX{} packages has been added. + +@item +Numbers of bugs have been fixed, many minor features have been added. +@end itemize + +@heading News in 11.88 + +@itemize @bullet +@item +@code{TeX-PDF-mode} is now enabled by default. + +@item +Now @code{TeX-previous-error} works with @TeX{} commands if the new +option @code{TeX-parse-all-errors} is non-nil, which is the default. +When this option is non-nil, an overview of errors and warnings reported +by the @TeX{} compiler can be opened with @kbd{M-x TeX-error-overview +@key{RET}}. +@ifclear rawfile +@xref{Debugging}, for details. +@end ifclear + +@item +Style file authors are encouraged to distinguish common from expert +macros and environments, and mark the latter using +@code{TeX-declare-expert-macros} and +@code{LaTeX-declare-expert-environments}. + +Users can then restrict completion using +@code{TeX-complete-expert-commands}. + +@item +Management of @LaTeX{} package options in the parser was improved. You +might need to reparse your documents, especially if you loaded the +@samp{babel} package with language options. + +@item +Now you can insert @samp{$...$} or @samp{\(...\)} by typing a single +@kbd{$}. To do this, customize the new option @samp{TeX-electric-math}. +@code{TeX-math-close-double-dollar} was removed. +@ifclear rawfile +@xref{Quotes}, for details. +@end ifclear + +@item +@kbd{C-c @key{RET} documentclass @key{RET}} completes with all available +@LaTeX{} classes, if the @code{TeX-arg-input-file-search} variable is +non-nil. Completion for class options of the standard @LaTeX{} classes +is provided as well. + +@item +New user options @code{LaTeX-default-author}, +@code{LaTeX-fontspec-arg-font-search}, +@code{LaTeX-fontspec-font-list-default}, @code{TeX-date-format}, and +@code{TeX-insert-braces-alist}. A new possible value +(@code{show-all-optional-args}) for +@code{TeX-insert-macro-default-style} was added. The default value of +@code{TeX-source-correlate-method} has been changed. + +@item +@samp{biblatex} support was greatly expanded. If parsing is enabled, +@AUCTeX{} looks at @samp{backend} option to decide whether to use Biber +or Bib@TeX{}. The @code{LaTeX-biblatex-use-Biber} variable was changed to +be file local only and is no more customizable. + +@item +With some @LaTeX{} classes, the default environment suggested by +@code{LaTeX-environment} (@kbd{C-c C-e}) when the current environment is +@samp{document} was changed. With @samp{beamer} class the default +environment is @samp{frame}, with @samp{letter} it is @samp{letter}, +with @samp{slides} it is @samp{slide}. + +@item +Brace pairing feature was enhanced in @LaTeX{} documents. Support for +@samp{\bigl}, @samp{\Bigl}, @samp{\biggl} and @samp{\Biggl}, the same +as the one for @samp{\left}, was added to @code{TeX-insert-macro}. +For example, @kbd{C-c @key{RET} bigl @key{RET} ( @key{RET}} inserts +@samp{\bigl(\bigr)}. + +You can insert brace pair @samp{()}, @samp{@{@}} and @samp{[]} by typing +a single left brace if the new user option +@code{LaTeX-electric-left-right-brace} is enabled. + +Macros @samp{\langle}, @samp{\lfloor} and @samp{\lceil}, which produce +the left part of the paired braces, are treated similarly as @samp{(}, +@samp{@{} and @samp{[} during the course of @code{TeX-insert-macro}. +@ifclear rawfile +@xref{Quotes}, for details. +@end ifclear + +@item +Support for dozens of @LaTeX{} packages was added. + +@item +Tabular-like environments (@samp{tabular}, @samp{tabular*}, @samp{tabularx}, @samp{tabulary}, @samp{array}, +@samp{align}, ...) are indented in a nicer and more informative way when the +column values of a table line are written across multiple lines in the +tex file. + +@item +The suitable number of ampersands are inserted when you insert @samp{array}, +@samp{tabular} and @samp{tabular*} environments with @kbd{C-c C-e}. Similar +experience is obtained if you terminate rows in these environments with +@kbd{C-c @key{LFD}}. It supplies line break macro @samp{\\} and inserts +the suitable number of ampersands on the next line. + +Similar supports are provided for various @samp{amsmath} environments. + +@ifclear rawfile +@xref{Tabular-like}, for details. +@end ifclear + +@item +Commands for narrowing to a group (@code{TeX-narrow-to-group}) and to +@LaTeX{} environments (@code{LaTeX-narrow-to-environment}) were added. + +@item +Now arbitrary options can be passed to the @TeX{} processor on a +per file basis using the @code{TeX-command-extra-options} option. +@ifclear rawfile +@xref{Processor Options}, for details. +@end ifclear + +@item +Now @kbd{C-c C-e document @key{RET}}, in an empty document, prompts for +@samp{\usepackage} macros in addition to @samp{\documentclass}. + +@item +@code{TeX-add-style-hook} has now a third argument to tell @AUCTeX{} for +which dialect (@LaTeX{}, Texinfo or Bib@TeX{}) the style hook is +registers. Labelling style hook by dialect will avoid applying them not +in the right context. + +@item +There have been lots of bug fixes and feature additions. +@end itemize + +@heading News in 11.87 + +@itemize @bullet +@item +@AUCTeX{} now supports Biber in conjunction with biblatex in addition to +Bib@TeX{}. + +@item +Each @AUCTeX{} mode now has its own abbrev table. On Emacsen which +provide the possibility to inherit abbrevs from other tables, the +abbrevs from the Text mode abbrev table are available as well. Newly +defined abbrevs are written to the mode-specific tables, though. + +@item +The file @samp{tex-fptex.el} was removed. + +@item +Forward/backward search for Evince has been improved. If Emacs is +compiled with DBUS support and a recent Evince version (3.x) is +installed, the communication goes over the desktop bus instead of the +command line, resulting in more accurate positioning of point in Emacs +and highlighting of the target paragraph in Evince. + +@item +A problem where Ghostscript threw an @samp{/invalidfileaccess} error when +running @previewlatex{} was fixed. + +@item +A lot of smaller fixes and additions have been made. +@end itemize + + +@heading News in 11.86 + +@itemize @bullet +@item +Parsing of @LaTeX{} output was improved. It is now less likely that +@AUCTeX{} opens a non-existent file upon calling @code{TeX-next-error}; +a problem for example encountered when using MiK@TeX{} 2.8. In addition +quoted file names as emitted by MiK@TeX{} are now supported. + +@item +A new framework for the definition and selection of viewers was +implemented. If you have customizations regarding viewers you will have +to redo them in this new framework or reenable the old one. +@ifset rawfile +See the section on viewers in the manual for details. +@end ifset +@ifclear rawfile +@xref{Starting Viewers}, for details. +@end ifclear + +@item +Comprehensive editing support for PSTricks was added. + +@item +Support for various @LaTeX{} packages was added, e.g.@: @samp{tabularx}, +@samp{CJK}, and @samp{hyperref}. + +@item +An easy way to switch between @TeX{} engines (PDF@TeX{}, Lua@TeX{}, +Xe@TeX{}, Omega) was added. + +@item +Support for Sync@TeX{} was added. This involves the command line +options for @LaTeX{} and the viewer. + +@item +Folding can now be customized to use macro arguments as replacement +text. + +@item +@samp{preview.sty} now works with Xe@TeX{}. + +@item +A lot of smaller and larger bugs have been squashed. +@end itemize + +@heading News in 11.85 + +@itemize @bullet + +@item +Font locking has been improved significantly. It is now less prone to +color bleeding which could lead to high resource usage. In addition it +now includes information about @LaTeX{} macro syntax and can indicate +syntactically incorrect macros in @LaTeX{} mode. + +@item +The license was updated to GPLv3. + +@item +Support for the nomencl, flashcards and comment @LaTeX{} packages as +well as the Icelandic language option of babel were added. + +@item +Support for folding of math macros was added. + +@item +Lots of minor bugs in features and documentation fixed. +@end itemize + +@heading News in 11.84 + +@itemize @bullet + +@item +There have been problems with the @option{-without-texmf-dir} option to +@samp{configure} when the value of @option{-with-kpathsea-sep} was set or +determined for an installation system with a default different from that +of the runtime system. @code{with-kpathsea-sep} has been removed; the +setting is now usually determined at runtime. + +Due to this and other problems, @previewlatex{} in the released XEmacs +package failed under Windows or with anything except recent 21.5 +XEmacsen. + +@item +@AUCTeX{} and @previewlatex{} have been changed in order to accommodate +file names containing spaces. @previewlatex{} now tolerates bad +PostScript code polluting the stack (like some Omega fonts). + +@item +@samp{preview.sty} had in some cases failed to emit PostScript header +specials. + +@item +Support for folding of comments was added. + +@item +The @code{polish} language option of the babel @LaTeX{} package as well as +the polski @LaTeX{} package are now supported. Most notably this means +that @AUCTeX{} will help to insert quotation marks as defined by @file{polish.sty} +(@code{"`..."'}) and @file{polski.sty} (@code{,,...''}). + +@item +The @TeX{} tool bar is now available and enabled by default in plain +@TeX{} mode. +@ifclear rawfile +@xref{Processing Facilities}. +@end ifclear + +@item +Bug fix in the display of math subscripts and superscripts. + +@item +Bug fix @code{TeX-doc} for Emacs 21. + +@item +There has been quite a number of other bug fixes to various features and +documentation across the board. + +@end itemize + +@heading News in 11.83 + +@itemize @bullet +@item +The new function @code{TeX-doc} provides easy access to documentation +about commands and packages or information related to @TeX{} and friends +in general. +@ifset rawfile +It is accessible with the key binding @kbd{C-c ?} or the +@samp{Find Documentation...} entry in the mode menus. +@end ifset +@ifclear rawfile +@xref{Documentation}. +@end ifclear + +@item +You can now get rid of generated intermediate and output files by means +of the new @samp{Clean} and @samp{Clean All} entries in +@code{TeX-command-list} accessible with @kbd{C-c C-c} or the Command +menu. +@ifclear rawfile +@xref{Cleaning}. +@end ifclear + +@item +Support for forward search with PDF files was added. That means you can +jump to a place in the output file corresponding to the position in the +source file. +@ifset rawfile +Currently this only works if you use the pdfsync @LaTeX{} package and +xpdf as your PDF viewer. The accuracy is in the range of +/-1 page. +@end ifset +@ifclear rawfile +@xref{Viewing}. +@end ifclear + +Adding support for this feature required the default value of the +variable @code{TeX-output-view-style} to be changed. Please make sure +you either remove any customizations overriding the new default or +incorporate the changes into your customizations if you want to use this +feature. + +@item +@TeX{} error messages of the @option{-file-line-error} kind are now +understood in @AUCTeX{} and @previewlatex{} (parsers are still +separate). + +@item +Bug fix in XyM@TeX{} support. + +@item +The @LaTeX{} tool bar is now enabled by default. +@ifclear rawfile +@xref{Processing Facilities}. +@end ifclear + +@end itemize + +@heading News in 11.82 + +@itemize @bullet +@item +Support for the MinionPro @LaTeX{} package was added. + +@item +Warnings and underfull/overfull boxes are now being indicated in the +echo area after a @LaTeX{} run, if the respective debugging options are +activated with @code{TeX-toggle-debug-warnings} (@kbd{C-c C-t C-w}) or +@code{TeX-toggle-debug-bad-boxes} (@kbd{C-c C-t C-b}). In this case +@code{TeX-next-error} will find these warnings in addition to normal +errors. + +The key binding @kbd{C-c C-w} for @code{TeX-toggle-debug-bad-boxes} +(which was renamed from @code{TeX-toggle-debug-boxes}) now is +deprecated. + +@item +@AUCTeX{} now can automatically insert a pair of braces after typing +@key{_} or @key{^} in math constructs if the new variable +@code{TeX-electric-sub-and-superscript} is set to a non-nil value. + +@item +Some language-specific support for French was added. There now is +completion support for the commands provided by the @samp{frenchb} (and +@samp{francais}) options of the babel @LaTeX{} package and easier input +of French quotation marks (@code{\og ...\fg}) which can now be +inserted by typing @key{"}. + +@item +Completion support for options of some @LaTeX{} packages was added. + +@item +@cindex @file{auctex.el} +@cindex @file{tex-site.el} +Already in version 11.81 the way to activate @AUCTeX{} changed +substantially. This should now be done with @code{(load "auctex.el" nil +t t)} instead of the former @code{(require 'tex-site)}. Related to this +change @file{tex-mik.el} does not load @file{tex-site.el} anymore. That +means if you used only @code{(require 'tex-mik)} in order to activate +@AUCTeX{}, you have to add @code{(load "auctex.el" nil t t)} before the +latter statement. +@ifset rawfile +More detailed information can be found in the installation instructions +(file @file{INSTALL}). +@end ifset +@ifclear rawfile +@xref{Loading the package}. +@end ifclear + +@item +Handling of verbatim constructs was consolidated across @AUCTeX{}. This +resulted in the @fontlatex{}-specific variables +@code{font-latex-verb-like-commands}, @code{font-latex-verbatim-macros}, +and @code{font-latex-verbatim-environments} being removed and the more +general variables @code{LaTeX-verbatim-macros-with-delims}, +@code{LaTeX-verbatim-macros-with-braces}, and +@code{LaTeX-verbatim-environments} being added. + +@item +The output of a Bib@TeX{} run is now checked for warnings and errors, +which are reported in the echo area. + +@item +The aliases for @code{font-latex-title-fontify} were removed. Use +@code{font-latex-fontify-sectioning} instead. + +@item +The problem that Japanese macros where broken across lines was fixed. + +@item +Various bug fixes. +@end itemize + +@heading News in 11.81 + +@itemize @bullet +@item +@code{LaTeX-mark-section} now marks subsections of a given section as +well. The former behavior is available via the prefix argument. + +@item +@previewlatex{} which was previously available separately became a +subsystem of @AUCTeX{}. There is no documented provision for building +or installing @previewlatex{} separately. It is still possible to use +and install @AUCTeX{} without @previewlatex{}, however. + +@item +The installation procedures have been overhauled and now also install +startup files as part of the process (those had to be copied manually +previously). You are advised to remove previous installations of +@AUCTeX{} and @previewlatex{} before starting the installation +procedure. A standard installation from an unmodified tarball no longer +requires Makeinfo or Perl. + +Also note that the way @AUCTeX{} is supposed to be activated changed. +Instead of @code{(require 'tex-site)} you should now use @code{(load +"auctex.el" nil t t)}. While the former method may still work, the new +method has the advantage that you can deactivate a preactivated +@AUCTeX{} with the statement @code{(unload-feature 'tex-site)} before +any of its modes have been used. This may be important especially for +site-wide installations. + +@item +Support for the babel @LaTeX{} package was added. + +@item +Folding a buffer now ensures that the whole buffer is fontified before +the actual folding is carried out. If this results in unbearably long +execution times, you can fall back to the old behavior of relying on +stealth font locking to do this job in the background by customizing the +variable @code{TeX-fold-force-fontify}. + +@item +Folded content now reveals part of its original text in a tooltip or the +echo area when hovering with the mouse pointer over it. + +@item +The language-specific insertion of quotation marks was generalized. The +variables @code{LaTeX-german-open-quote}, +@code{LaTeX-german-close-quote}, @code{LaTeX-german-quote-after-quote}, +@code{LaTeX-italian-open-quote}, @code{LaTeX-italian-close-quote}, and +@code{LaTeX-italian-quote-after-quote} are now obsolete. If you are not +satisfied with the default settings, you should customize +@code{TeX-quote-language-alist} instead. + +@item +Similar to language-specific quote insertion, @AUCTeX{} now helps you +with hyphens in different languages as well. +@ifclear rawfile +@xref{European}, for details. +@end ifclear + +@item +Fill problems in Japanese text introduced in @AUCTeX{} 11.55 were fixed. +@AUCTeX{} tries not to break lines between 1-byte and 2-byte chars. +These features will work in Chinese text, too. + +@item +The scaling factor of the fontification of sectioning commands can now +be customized using the variable @code{font-latex-fontify-sectioning}. +This variable was previously called @code{font-latex-title-fontify}; In +this release we provide an alias but this will disappear in one of the +the next releases. The faces for the sectioning commands are now called +@code{font-latex-sectioning-@var{N}-face} (@var{N}=0@dots{}5) instead of +@code{font-latex-title-@var{N}-face} (@var{N}=1@dots{}4). Analogously +the names of the variables holding the related keyword lists were +changed from @code{font-latex-title-@var{N}-keywords} to +@code{font-latex-sectioning-@var{N}-keywords}. +@ifclear rawfile +@xref{Font Locking}, for details. +@end ifclear +Make sure to adjust your customizations. + +@item +Titles in beamer slides marked by the ``\frametitle'' command are know +displayed with the new face @code{font-latex-slide-title-face}. You can +add macros to be highlighted with this face to +@code{font-latex-match-slide-title-keywords}. + +@item +Of course a lot of bugs have been fixed. +@end itemize + +@heading News in 11.55 + +@itemize @bullet +@item +A bug was fixed which lead to the insertion of trailing whitespace +during filling. In particular extra spaces were added to sentence +endings at the end of lines. You can make this whitespace visible by +setting the variable @code{show-trailing-whitespace} to @code{t}. If +you want to delete all trailing whitespace in a buffer, type @kbd{M-x +delete-trailing-whitespace @key{RET}}. + +@item +A bug was fixed which lead to a @samp{*Compile-Log*} buffer popping up +when the first @LaTeX{} file was loaded in an Emacs session. + +@item +On some systems the presence of an outdated Emacspeak package lead to +the error message @samp{File mode specification error: (error "Variable +binding depth exceeds max-specpdl-size")}. Precautions were added which +prevent this error from happening. But nevertheless, it is advised to +upgrade or uninstall the outdated Emacspeak package. + +@item +The value of @code{TeX-macro-global} is not determined during +configuration anymore but at load time of @AUCTeX{}. Consequently the +associated configuration option @option{--with-tex-input-dirs} was +removed. + +@item +Support for the @LaTeX{} Japanese classes @samp{jsarticle} and +@samp{jsbook} was added. +@end itemize + +@heading News in 11.54 + +@itemize @bullet +@item +The parser (used e.g.@: for @code{TeX-auto-generate-global}) was extended +to recognize keywords common in @LaTeX{} packages and classes, like +``\DeclareRobustCommand'' or ``\RequirePackage''. Additionally a bug +was fixed which led to duplicate entries in @AUCTeX{} style files. + +@item +Folding can now be done for paragraphs and regions besides single +constructs and the whole buffer. With the new @code{TeX-fold-dwim} +command content can both be hidden and shown with a single key binding. +In course of these changes new key bindings for unfolding commands where +introduced. The old bindings are still present but will be phased out +in future releases. + +@item +Info files of the manual now have a .info extension. + +@item +There is an experimental tool bar support now. It is not activated by +default. If you want to use it, add +@lisp +(add-hook 'LaTeX-mode-hook 'LaTeX-install-toolbar) +@end lisp +to your init file. + +@item +The manual now contains a new chapter ``Quick Start''. It explains the +main features and how to use them, and should be enough for a new user +to start using @AUCTeX{}. + +@item +A new section ``Font Locking'' was added to the manual which explains +syntax highlighting in @AUCTeX{} and its customization. Together with +the sections related to folding and outlining, the section is part of +the new chapter ``Display''. + +@item +Keywords for syntax highlighting of @LaTeX{} constructs to be typeset in +bold, italic or typewriter fonts may now be customized. Besides the +built-in classes, new keyword classes may be added by customizing the +variable @code{font-latex-user-keyword-classes}. The customization +options can be found in the customization group +@code{font-latex-keywords}. + +@item +Verbatim content is now displayed with the @samp{fixed-pitch} face. (GNU +Emacs only) + +@item +Syntax highlighting should not spill out of verbatim content +anymore. (GNU Emacs only) + +@item +Verbatim commands like @samp{\verb|...|} will not be broken anymore +during filling. + +@item +You can customize the completion for graphic files with +@code{LaTeX-includegraphics-read-file}. + +@item +Support for the @LaTeX{} packages @samp{url}, @samp{listings}, +@samp{jurabib} and @samp{csquotes} was added with regard to command +completion and syntax highlighting. + +@item +Performance of fontification and filling was improved. + +@item +Insertion of nodes in Texinfo mode now supports completion of existing +node names. + +@item +Setting the variable @code{LaTeX-float} to @code{nil} now means that you +will not be prompted for the float position of figures and tables. You +can get the old behaviour of @code{nil} by setting the variable to +@code{""}, i.e.@: an empty string. +@ifclear rawfile +See also @ref{Floats}. +@end ifclear + +@item +The XEmacs-specific bug concerning @code{overlays-at} was fixed. + +@item +Lots of bug fixes. +@end itemize + +@heading News in 11.53 + +@itemize @bullet +@item +The @LaTeX{} math menu can include Unicode characters if your Emacs +built supports it. See the variable +@ifset rawfile +@code{LaTeX-math-menu-unicode}. +@end ifset +@ifclear rawfile +@code{LaTeX-math-menu-unicode}, @ref{Mathematics}. +@end ifclear + +@item +Bug fixes for XEmacs. + +@c The following items weren't present at release time of 11.53: +@item +Completion for graphic files in the @TeX{} search path has been added. + +@item +@command{start} is used for the viewer for MiK@TeX{} and fp@TeX{}. + +@item +The variable @code{TeX-fold-preserve-comments} can now be customized to +deactivate folding in comments. +@end itemize + +@heading News in 11.52 +@c Not present at release time of 11.52. + +@itemize @bullet +@item +Installation and menus under XEmacs work again (maybe for the first +time). + +@item +Fontification of subscripts and superscripts is now disabled when the +fontification engine is not able to support it properly. + +@item +Bug fixes in the build process. +@end itemize + +@heading News in 11.51 +@c Not present at release time of 11.51. + +@itemize @bullet +@item +PDF@TeX{} and Source Special support did not work with @ConTeXt{}, +this has been fixed. Similar for Source Special support under Windows. + +@item +Omega support has been added. + +@item +Bug fixes in the build process. + +@item +@code{TeX-fold} now supports folding of environments in Texinfo mode. +@end itemize + +@heading News in 11.50 + +@itemize @bullet +@item +The use of source specials when processing or viewing the document can +now be controlled with the new @code{TeX-source-specials} minor mode +which can be toggled via an entry in the Command menu or the key binding +@kbd{C-c C-t C-s}. If you have customized the variable +@code{TeX-command-list}, you have to re-initialize it for this to work. +This means to open a customization buffer for the variable by typing +@kbd{M-x customize-variable @key{RET} TeX-command-list @key{RET}}, selecting +``Erase Customization'' and do your customization again with the new +default. + +@item +The content of the command menu now depends on the mode (plain @TeX{}, +@LaTeX{}, @ConTeXt{} etc.). Any former customization of the variable +@code{TeX-command-list} has to be erased. Otherwise the command menu +and the customization will not work correctly. + +@item +Support for hiding and auto-revealing macros, e.g.@: footnotes or +citations, and environments in a buffer was +@ifset rawfile +added. +@end ifset +@ifclear rawfile +added, @ref{Folding}. +@end ifclear + +@item +You can now control if indentation is done upon typing @key{RET} by +customizing the variable +@ifset rawfile +@code{TeX-newline-function}. +@end ifset +@ifclear rawfile +@code{TeX-newline-function}, @ref{Indenting}. +@end ifclear + +@item +Limited support for @code{doc.sty} and @code{ltxdoc.cls} (@samp{dtx} +files) was added. The new doc@TeX{} mode provides functionality for +editing documentation parts. This includes formatting (indenting and +filling), adding and completion of macros and environments while staying +in comments as well as syntax highlighting. (Please note that the mode +is not finished yet. For example syntax highlighting does not work yet +in XEmacs.) + +@item +For macro completion in doc@TeX{} mode the @AUCTeX{} style files +@file{doc.el}, @file{ltxdoc.el} and @file{ltx-base.el} were included. +The latter provides general support for low-level @LaTeX{} macros and +may be used with @LaTeX{} class and style files as well. It is +currently not loaded automatically for those files. + +@item +Support for @ConTeXt{} with a separate @ConTeXt{} mode is now included. +Macro definitions for completion are available in Dutch and English. + +@item +The filling and indentation code was overhauled and is now able to +format commented parts of the source syntactically correct. Newly +available functionality and customization options are explained in the +manual. + +@item +Filling and indentation in XEmacs with @previewlatex{} and activated +previews lead to the insertion of whitespace before multi-line previews. +@AUCTeX{} now contains facilities to prevent this problem. + +@item +If @code{TeX-master} is set to @code{t}, @AUCTeX{} will now query for a +master file only when a new file is opened. Existing files will be left +alone. The new function @code{TeX-master-file-ask} (bound to @kbd{C-c +_} is provided for adding the variable manually. + +@item +Sectioning commands are now shown in a larger font on display devices +which support such fontification. The variable +@code{font-latex-title-fontify} can be customized to restore the old +appearance, i.e.@: the usage of a different color instead of a change in +size. + +@item +Support for @code{alphanum.sty}, @code{beamer.cls}, @code{booktabs.sty}, +@code{captcont.sty}, @code{emp.sty}, @code{paralist.sty}, +@code{subfigure.sty} and @code{units.sty}/@code{nicefrac.sty} was added. +Credits go to the authors mentioned in the respective @AUCTeX{} style +files. + +@item +Inserting graphics with @kbd{C-c @key{RET} includegraphics @key{RET}} was improved. +See the variable @code{LaTeX-includegraphics-options-alist}. +@c FIXME: Document this in the main part of the manual + +@item +If @code{LaTeX-default-position} is @code{nil}, don't prompt for +position arguments in Tabular-like +@ifset rawfile +environments. +@end ifset +@ifclear rawfile +environments, see @ref{Tabular-like}. +@end ifclear + +@item +Completion for available packages when using @kbd{C-c @key{RET} usepackage +@key{RET}} was improved on systems using the kpathsea library. + +@item +The commenting functionality was fixed. The separate functions for +commenting and uncommenting were unified in one function for paragraphs +and regions respectively which do both. + +@item +Syntax highlighting can be customized to fontify quotes delimited by +either >>German<< or <<French>> quotation marks by changing the variable +@code{font-latex-quotes}. + +@item +Certain @TeX{}/@LaTeX{} keywords for functions, references, variables +and warnings will now be fontified specially. You may add your own +keywords by customizing the variables +@code{font-latex-match-function-keywords}, +@code{font-latex-match-reference-keywords}, +@code{font-latex-match-variable-keywords} and +@code{font-latex-match-warning-keywords}. + +@item +If you include the style files @file{german} or @file{ngerman} in a +document (directly or via the @samp{babel} package), you should now +customize @code{LaTeX-german-open-quote}, +@code{LaTeX-german-close-quote} and +@code{LaTeX-german-quote-after-quote} instead of @code{TeX-open-quote}, +@code{TeX-close-quote} and @code{TeX-quote-after-quote} if you want to +influence the type of quote insertion. + +@item +Upon viewing an output file, the right viewer and command line options +for it are now determined automatically by looking at the extension of +the output file and certain options used in the source file. The +behavior can be adapted or extended respectively by customizing the +variable @code{TeX-output-view-style}. + +@item +You can control whether @code{TeX-insert-macro} (@kbd{C-c @key{RET}}) ask for +all optional arguments by customizing the variable +@ifset rawfile +@code{TeX-insert-macro-default-style}. +@end ifset +@ifclear rawfile +@code{TeX-insert-macro-default-style}, @ref{Completion}. +@end ifclear + +@item +@code{TeX-run-discard} is now able to completely detach a process that +it started. + +@item +The build process was enhanced and is now based on @code{autoconf} +making installing @AUCTeX{} a mostly automatic process. See +@ifset rawfile +the files @file{INSTALL} and @file{INSTALL.windows} +@end ifset +@ifclear rawfile +@ref{Installation} and @ref{Installation under MS Windows} +@end ifclear +for details. +@end itemize + +@heading News in 11.14 + +@itemize @bullet +@item +Many more @LaTeX{} and @LaTeX{}2e commands are supported. +Done by Masayuki Ataka @email{ataka@@milk.freemail.ne.jp} +@end itemize + +@heading News in 11.12 + +@itemize @bullet +@item +Support for the KOMA-Script classes. +Contributed by Mark Trettin @email{Mark.Trettin@@gmx.de}. +@end itemize + +@heading News in 11.11 + +@itemize @bullet +@item +Support for @file{prosper.sty}, see @url{http://prosper.sourceforge.net/}. +Contributed by Phillip Lord @email{p.lord@@russet.org.uk}. +@end itemize + +@heading News in 11.10 + +@itemize @bullet +@item +@code{comment-region} now inserts @t{%%} by default. +Suggested by "Davide G. M. Salvetti" @email{salve@@debian.org>}. +@end itemize + +@heading News in 11.06 + +@itemize @bullet +@item +You can now switch between using the @file{font-latex} (all emacsen), +the @file{tex-font} (Emacs 21 only) or no special package for font +locking. Customize @code{TeX-install-font-lock} for this. +@end itemize + +@heading News in 11.04 + +@itemize @bullet +@item +Now use @t{-t landscape} by default when landscape option appears. +Suggested by Erik Frisk @email{frisk@@isy.liu.se}. +@end itemize + +@heading News in 11.03 + +@itemize @bullet +@item +Use @file{tex-fptex.el} for fp@TeX{} support. +Contributed by Fabrice Popineau @email{Fabrice.Popineau@@supelec.fr}. +@end itemize + +@heading News in 11.02 + +@itemize @bullet +@item +New user option @code{LaTeX-top-caption-list} specifies environments +where the caption should go at top. +Contributed by @email{ataka@@milk.freemail.ne.jp} (Masayuki Ataka). + +@item +Allow explicit dimensions in @file{graphicx.sty}. +Contributed by @email{ataka@@milk.freemail.ne.jp} (Masayuki Ataka). + +@item +Limited support for @file{verbatim.sty}. +Contributed by @email{ataka@@milk.freemail.ne.jp} (Masayuki Ataka). + +@item +Better support for amsmath items. +Patch by @email{ataka@@milk.freemail.ne.jp} (Masayuki Ataka). + +@item +More accurate error parsing. +Added by David Kastrup @email{David.Kastrup@@t-online.de}. +@end itemize + +@heading News in 11.01 + +@itemize @bullet +@item +Bug fixes. +@end itemize + +@c Local Variables: +@c mode: texinfo +@c TeX-master: "auctex" +@c End: diff --git a/elpa/auctex-13.1.3/doc/copying.texi b/elpa/auctex-13.1.3/doc/copying.texi new file mode 100644 index 0000000..b273df1 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/copying.texi @@ -0,0 +1,48 @@ +@include macros.texi +@c ----------------------- +@cindex Copying +@cindex Copyright +@cindex GPL +@cindex General Public License +@cindex License +@c @cindex Free +@c @cindex Free software +@c @cindex Distribution +@c @cindex Right +@cindex Warranty + +(This text is stolen from the Texinfo manual, Edition 4.0). + +The programs currently being distributed that relate to @previewlatex{} +include lisp files for Emacs and style files for @LaTeX{}. These +programs are @dfn{free}; this means that everyone is free to use them +and free to redistribute them on a free basis. The @previewlatex{} +related programs 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 programs that relate to @previewlatex{}, that you receive +source code or else can get it if you want it, that you can change these +programs 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 the @previewlatex{} related programs, 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 the programs that relate to +@previewlatex{}. If these programs 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 programs currently being +distributed that relate to @previewlatex{} are found in the General Public +Licenses that accompany them. diff --git a/elpa/auctex-13.1.3/doc/faq.texi b/elpa/auctex-13.1.3/doc/faq.texi new file mode 100644 index 0000000..a6122ec --- /dev/null +++ b/elpa/auctex-13.1.3/doc/faq.texi @@ -0,0 +1,158 @@ +@c This is part of the AUCTeX Manual. +@c Copyright (C) 2004-2014, 2021, 2022 Free Software Foundation, Inc. +@c See the file auctex.texi for copying conditions. +@ifset rawfile +@include macros.texi +@chapheading Frequently Asked Questions about @AUCTeX{} +@end ifset + +@c We should switch to sectioning commands instead of items when this +@c list grows. Keep in mind to formulate short questions because +@c section headings will not be broken in contrast to items. +@enumerate +@item +Something is not working correctly. What should I do? + +Well, you might have guessed it, the first place to look is in the +available documentation packaged with @AUCTeX{}. This could be the +release notes (in the @file{RELEASE} file) or the news section of the +manual in case you are experiencing problems after an upgrade, the +@file{INSTALL} file in case you are having problems with the +installation, the section about bugs in the manual in case you +encountered a bug or the relevant sections in the manual for other +related problems. + +If this did not help, you can send a bug report to the @AUCTeX{} bug +reporting list by using the command @kbd{M-x TeX-submit-bug-report @key{RET}}. +But before you do this, you can try to get more information about the +problem at hand which might also help you locate the cause of the error +yourself. + +First, you can try to generate a so-called backtrace which shows the +functions involved in a program error. In order to do this, start Emacs +with the command line @samp{emacs --debug-init} and/or put the line + +@lisp +(setq debug-on-error t) +@end lisp + +as the first line into your init file. After Emacs has started, you can +load a file which triggers the error and a new window should pop up +showing the backtrace. If you get such a backtrace, please include it +in the bug report. + +Second, you can try to figure out if something in your personal or site +configuration triggers the error by starting Emacs without such +customizations. You can do this by invoking Emacs with the following +command line, depending on the installation scheme of @AUCTeX{} and your +@acronym{OS}: +@itemize +@item +If you installed @AUCTeX{} from @acronym{ELPA}, use @samp{emacs -q +-no-site-file --eval "(progn (setq package-load-list '((auctex t))) +(package-initialize))"}. The @option{--eval} option activates only +@AUCTeX{} among all installed @acronym{EPLA} packages. +@item +If you installed @AUCTeX{} via traditional +@command{configure}--@command{make} scheme, use @samp{emacs -q +-no-site-file -l auctex}. The @option{-l} option loads @file{auctex.el} +which you normally do in your init file. +@item +In both above cases, use @samp{runemacs} instead of @samp{emacs} on +windows. +@end itemize + +After you +have started Emacs like this, you can load the file triggering the +error. If everything is working now, you know that you have to search +either in the site configuration file or your personal init file for +statements related to the problem. + +@item +What versions of Emacs are supported? + +@AUCTeX{} was tested with @w{GNU Emacs 25.1}. Older versions may work but +are unsupported. + +@item +What should I do when @command{./configure} does not find programs like @command{latex}? + +This is problem often encountered on Windows. Make sure that the +@env{PATH} environment variable includes the directories containing the +relevant programs, as described in +@ifset rawfile +the file @file{INSTALL.windows} +@end ifset +@ifclear rawfile +@ref{Installation under MS Windows,,,auctex,the @AUCTeX{} manual}. +@end ifclear + +@item +Why doesn't the completion, style file, or multifile stuff work? + +It must be enabled first, insert this in your init file: + +@lisp +(setq-default TeX-master nil) +(setq TeX-parse-self t) +(setq TeX-auto-save t) +@end lisp + +Read also the chapters about parsing and multifile documents in the +manual. +@ifclear rawfile +@xref{Parsing Files} and @ref{Multifile}. +@end ifclear + +@item +Why doesn't @code{TeX-save-document} work? + +@code{TeX-check-path} has to contain "@file{./}" somewhere. + +@item +Why is the information in @file{foo.tex} forgotten when I save +@file{foo.bib}? + +For various reasons, @AUCTeX{} ignores the extension when it stores +information about a file, so you should use unique base names for your +files. E.g.@: rename @file{foo.bib} to @file{foob.bib}. + +@item +Why doesn't @AUCTeX{} signal when processing a document is done? + +If the message in the minibuffer stays "Type `C-c C-l' to display +results of compilation.", you probably have a misconfiguration in your +init file (@file{.emacs}, @file{init.el} or similar). To track this +down either search in the @samp{*Messages*} buffer for an error message +or put @code{(setq debug-on-error t)} as the first line into your init +file, restart Emacs and open a @LaTeX{} file. Emacs will complain +loudly by opening a debugging buffer as soon as an error occurs. The +information in the debugging buffer can help you find the cause of the +error in your init file. + +@item +Why does @code{TeX-next-error} (@kbd{C-c `}) fail? + +If @code{TeX-file-line-error} is set to nil (not the default), these +sort of failures might be related to the the fact that when writing the +log file, @TeX{} puts information related to a file, including error +messages, between a pair of parentheses. In this scenario @AUCTeX{} +determines the file where the error happened by parsing the log file and +counting the parentheses. This can fail when there are other, +unbalanced parentheses present. + +Activating so-called @samp{file:line:error} messages for the log file usually +solves this issue, as these kind of messages are are easier to parse; +however, they may lack some details. Activation can be done either in +the configuration of your @TeX{} system (consult its manual to see where +this is) or by simply keeping the variable @code{TeX-file-line-error} to +the default value of non-nil. + +@item +What does @samp{AUC} stand for? + +@AUCTeX{} came into being at Aalborg University in Denmark. Back then +the Danish name of the university was Aalborg Universitetscenter; @samp{AUC} +for short. + +@end enumerate diff --git a/elpa/auctex-13.1.3/doc/fdl.texi b/elpa/auctex-13.1.3/doc/fdl.texi new file mode 100644 index 0000000..ef31dae --- /dev/null +++ b/elpa/auctex-13.1.3/doc/fdl.texi @@ -0,0 +1,506 @@ +@node GNU Free Documentation License +@appendixsec GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.3, 3 November 2008 + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software +Foundation, Inc. @uref{https://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{https://www.gnu.org/licenses/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + 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 group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.''@: line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/elpa/auctex-13.1.3/doc/history.texi b/elpa/auctex-13.1.3/doc/history.texi new file mode 100644 index 0000000..0595bb6 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/history.texi @@ -0,0 +1,1918 @@ +@include macros.texi +@section News in 10.0 + +@itemize @bullet + +@item +Disabled @code{LaTeX-hide-environment}. +Suggested by Christopher Allen <cpcallen@@ruah.dyndns.org>. + +@item +Changed default to lazy evaluation of @code{TeX-view-style} and +@code{LaTeX-command-style}. +Suggested by Peter Neergaard <turtle@@cs.bu.edu>. + +@item +Backindent when brace is at the start of a line. +Patch by Masashi Shimbo <shimbo@@cis.ibaraki.ac.jp>. + +@item +Added Emacs 21 font lock support. + +@item +@kbd{,} and @kbd{.} no longer removes italic correction. + +@item +@code{graphicx} and @code{graphics} style support. +Donated by Ryuichi Arafune <arafune@@ushioda.riec.tohoku.ac.jp>. + +@item +@code{LaTeX-math-abbrev-prefix} now accepts vector value. +Reported by Jan Vroonhof <vroonhof@@math.ethz.ch>. + +@item +Improved Texinfo support(more environments and html). +Patch by Akim Demaille <akim@@epita.fr>. + +@item +@code{danish} quotes support. +Suggested by arne@@daimi.au.dk (Arne Joergensen). + +@item +Some PDF support. + +@item +New @file{tex-mik.el} file for MiK@TeX{} support. + +@item +Some commands now have their own history. +Suggested by Werner LEMBERG <sx0005@@sx2.HRZ.Uni-Dortmund.DE>. + +@item +Use @code{\centering} instead of center environment in figures. +Patch by Stefan Monnier <foo@@acm.com>. + +@item +New @code{dwim} setting for @code{TeX-master} attempts to guess +a default master for new files. +Patch by Stefan Monnier <foo@@acm.com>. + +@item +@code{ngerman} style support. +Just a copy of the german style support. + +@item +Removed support for Emacs 18 and 19. + +@item @code{mdwlist} support. +Patch by Stephen Heilbronner <heilbron@@nm.informatik.uni-muenchen.de>. + +@item +Fixed various bugs with the babel package. + +@item @code{amsart} and @code{amsbook} now loads @code{amsthm} by default. +Patch by Rune Kleveland <runekl@@math.uio.no>. + +@item Fixed bug with file searching. +Reported by Berwin Turlach <bturlach@@maths.adelaide.edu.au>. + +@item Finalized index support, added index-related style files. +Patch by Carsten Dominik <dominik@@strw.leidenuniv.nl>. + +@item New style files for @file{varioref.sty} and @file{fancyref.sty}. +Patch by Carsten Dominik <dominik@@strw.leidenuniv.nl>. + +@item @code{texmathp} recognizes additional macros like @code{\fbox}. +Patch by Ulrik Vieth <vieth@@thphy.uni-duesseldorf.de>. + +@end itemize + +@section News in 9.9 + +@itemize @bullet +@item Bug fix in JLATEX recognition. Patch by +Tsutomu OKUMURA <oku@@nml.t.u-tokyo.ac.jp>. + +@item Bug fix in foils package sypport. +Suggested by Bernt Guldbrandtsen <bernt@@jupiter.ansci.iastate.edu>. + +@item Made @code{make install-contrib} compile the contributed lisp +files. +Suggested by Nils Ackermann <Nils.Ackermann@@math.uni-giessen.de>. + +@item In @code{texinfo-mode}, @kbd{C-c C-f C-d} now deletes the current +font, while @kbd{C-u C-c C-f @var{key}} changes it. @samp{@@dfn} moved +to @kbd{C-c C-f d}. Suggested by Christoph Wedler +<wedler@@fmi.uni-passau.de>. + +@item Fixed some custom types. +Patch by Markus Rost <markus.rost@@mathematik.uni-regensburg.de>. + +@item Support loading byte compiled files, even if +@code{TeX-byte-compile} is nil. +Patch by Christoph Wedler <wedler@@fmi.uni-passau.de>. + +@item The command to replace a LaTeX2e font should work more reliably +now. Patch by Christoph Wedler <wedler@@fmi.uni-passau.de>. + +@item Minor XEmacs packaging changes. +Patch by Christoph Wedler <wedler@@fmi.uni-passau.de>. + +@item @code{TeX-file-recurse} now accepts an integer value, max depth of +recursion. Patch by Alastair Burt <burt@@dfki.bde>. + +@item Simple imenu support for @LaTeX{}. + +@item Workaround for 20.3 bugs. + +@item The `Spell' command now works on all open buffers in the +document. Patch by Jason Stewart <jasons@@cs.unm.edu>. + +@item @kbd{C-c C-m} now puts content of region inside first empty brackets +in the macro, if any. Patch by Peter Thiemann <pjt@@cs.nott.ac.uk>. + +@item Update of @file{natbib.el} style file by Carsten Dominik +<dominik@@strw.LeidenUniv.nl>. + +@item Much better detection of @TeX{} math mode. Patch by Carsten Dominik +<dominik@@strw.LeidenUniv.nl>. + +@item New @samp{%n} escape in @code{TeX-command-list} for entering the +current line number. Suggested by "Lee, Sang-Min" +<smagus@@acorn.snu.ac.kr>. + +@item Doc fixes in manual. Patch by Gustavo Chaves +<gustavo@@cpqd.com.br>. + +@item Better reftex support for sections. Patch by Carsten Dominik +<dominik@@strw.LeidenUniv.nl>. + +@item Bug fixes in math card. Reported by "Ron Smith" +<rsmith@@eel.ufl.edu>. + +@item Better multifile support. Patch by Soren Dayton +<csdayton@@cs.uchicago.edu>. + +@item Don't expand abbreviations when @code{abbrev-mode} is nil. +Suggested by Alastair Burt <alastair.burt@@dfki.de>. + +@item @samp{direntry} support in manual, by SL Baur +<steve@@altair.xemacs.org>. +@end itemize + +@section News in 9.8 + +@itemize @bullet +@item Added @code{natbib.el} to support natbib.sty by Patrick W. Daly. +Submitted by Berwin A. Turlach @samp{<berwin.turlach@@anu.edu.au>}. + +@item +More @LaTeX{}2e support by Jan Vroonhof +@samp{<vroonhof@@math.ethz.ch>}.@refill + +@item Make @code{TeX-master} a local variable in Bib@TeX{} mode and set +it to true. This seems to be necessary to enable auto-parsing of a .bib +file. Patch by Berwin A. Turlach @samp{<berwin.turlach@@anu.edu.au>}. + +@item Support for Harvard style updated by Berwin A. Turlach +@samp{<berwin.turlach@@anu.edu.au>}. + +@item +Support for `natbib' package. +By Berwin Turlach @samp{<berwin.turlach@@anu.edu.au>}. + +@item +Finer control of automatic parsing of @TeX{} files: new variables +@code{TeX-auto-x-parse-length} and @code{TeX-auto-x-regexp-list}. +By Christoph Wedler @samp{<wedler@@fmi.uni-passau.de>}. + +@item +Finer control of indentation: new variables @code{LaTeX-document-regexp}, +@code{LaTeX-verbatim-regexp}, @code{LaTeX-begin-regexp}, +@code{LaTeX-end-regexp} and @code{LaTeX-indent-comment-start-regexp}. +By Christoph Wedler @samp{<wedler@@fmi.uni-passau.de>}. + +@item +When running @LaTeX{} on a region, do not complain about undefined +citations. See variable @code{TeX-region-extra}. +By Christoph Wedler @samp{<wedler@@fmi.uni-passau.de>}. + +@item +Split menu for LaTeX environments into submenus if number of +environments is larger than the value of the new variable +@code{LaTeX-menu-max-items}. +By Christoph Wedler @samp{<wedler@@fmi.uni-passau.de>}. + +@item +More reftex support with new @code{TeX-arg-ref} function. +By Soren Dayton @samp{<csdayton@@cs.uchicago.edu>}, with @file{amsmath} +support by Carsten Dominik @samp{<dominik@@strw.LeidenUniv.nl>}. + +@item +Minimal parser now recognize @code{usepackage}. +By Carsten Dominik @samp{<dominik@@strw.LeidenUniv.nl>}. + +@item +More amstex styles recognized. +By Carsten Dominik @samp{<dominik@@strw.LeidenUniv.nl>}. + +@item +Czech and Slovak support. +By Milan Zamazal @samp{<pdm@@fi.muni.cz>}. + +@end itemize + + +@section News in 9.7 + +@itemize @bullet +@item +Added support for customize. + +@item +Added minimal support for @code{sentence-end-double-space}. + +@end itemize + +@section News in 9.6 + +@itemize @bullet +@item +NT installation instructions added. + +@item +@file{func-doc.el} unbundled, as @file{word-help.el} will be added to +the standard Emacs distribution. See @url{http://www.ifi.uio.no/~jensthi/}. + +@item +@samp{$} is now of the syntax class `matched pair', suggested by Mats +Bengtsson @samp{<matsb@@s3.kth.se>}. + +@item +Now use @kbd{,} to enter multiple arguments to a @samp{\cite} or +@samp{\bibliography} command instead of @kbd{@key{ret}}. + +@item +Installation procedure is changed, read the @file{INSTALLATION} file. + +@item +LaCheck is unbundled. You can get @code{lacheck} from +@file{<URL:ftp://sunsite.dk/pub/text/lacheck/>} or alternatively +@code{chktex} from +@file{<URL:ftp://ftp.dante.de/pub/tex/support/chktex/>}. Search for +`chktex' in @file{tex.el} to see how to switch between them.@refill + +@item +Insert @code{(require 'font-latex)} to get better font lock support. + +@item +Bug fixes. + +@item +Better handling of subdirectories, suggested by Frederic Devernay +@samp{<Frederic.Devernay@@sophia.inria.fr>} and many others. +@end itemize + +@section News in 9.5 + +@itemize @bullet +@item Use the @file{func-doc.el} package to get context senstive help. +This is not autoloaded, you must load it explicitly with: + +@lisp +(require 'func-doc) +@end lisp + +@item +Bug fixes. + +@end itemize + +@section News in 9.4 + +@itemize @bullet +@item There is now a menu in @code{LaTeX-math-minor-mode}. + +@item +Bug fixes. +@end itemize + +@section News in 9.3 + +@itemize @bullet +@item +Bug fixes. +@end itemize + +@section News in 9.2 + +@itemize @bullet +@item +Bug fixes. + +@item +New file @file{bib-cite.el} contributed by Peter S. Galbraith +@samp{<rhogee@@bathybius.meteo.mcgill.ca>}. This file is not installed +or enabled by default and is not part of the basic AUC @TeX{} +package. If you have problems, questions, or suggestions, please direct +them to Peter. + +@item +New file @file{hilit-LaTeX.el} contributed by Peter S. Galbraith +@samp{<rhogee@@bathybius.meteo.mcgill.ca>}. This file is not installed +or enabled by default and is not part of the basic AUC @TeX{} +package. If you have problems, questions, or suggestions, please direct +them to Peter. + +@item +AUC @TeX{} is now less likely to suggest running Bib@TeX{} when it is +not needed. + +@item +Press @kbd{M-x LaTeX-209-to-2e @key{ret}} to make a stab at converting a +@LaTeX{} 2.09 header to @LaTeX{}2e. + +@item +@kbd{C-c C-m input @key{ret}} should be faster now on second try. + +@item +New variable @code{LaTeX-left-right-indent-level} controls the +indentation added by @samp{\left}. + +@item +@samp{\begin}, @samp{\end}, @samp{\left}, and @samp{\right} no longer +need to be at the beginning of the line to take effect. + +@item +You can now delete and replace @LaTeX{}2e style fonts. + +@item +Moved external commands to new menu. + +@item +@kbd{C-c C-m cite @key{ret}} will prompt for multiple keys. + +@item +Better handling of @samp{"} with @file{german.sty}. + +@item +New variable @code{LaTeX-paragraph-commands} lists @LaTeX{} commands +that shouldn't be formatted as part of a paragraph. + +@item +Older news moved to @file{HISTORY}. It is not @TeX{}info able, but you +can get a plaintext version with @samp{make HISTORY}. + +@item +See the new @file{ChangeLog} file for a more detailed list of changes. +The history section will now only contain user level changes. If you +send me a patch, please also provide a ChangeLog entry. +@end itemize + +@node Version 9.1 +@section News in 9.1 + +Coordinater: Per Abrahamsen, 1994. + +Alpha testers (in order of appearance): +Bernt Guldbrandtsen @samp{<bernt@@weinberg.pop.bio.aau.dk>}, +Kevin Scott @samp{<scottkj@@prl.philips.co.uk>}, +Lawrence R. Dodd @samp{<dodd@@roebling.poly.edu>}, +Michelangelo Grigni @samp{<mic@@cs.ucsd.edu>}, +David Aspinall @samp{<da@@dcs.edinburgh.ac.uk>}, +Frederic Devernay @samp{<Frederic.Devernay@@sophia.inria.fr>}, +Robert Estes @samp{<estes@@ece.ucdavis.edu>}, +Peter Whaite @samp{<peta@@cim.mcgill.ca>}, +Karl Eichwalder @samp{<karl@@pertron.central.de>}, +John Interrante @samp{<interran@@uluru.Stanford.EDU>}, +James A. Robinson @samp{<jimr@@simons-rock.edu>}, +Tim Carlson @samp{<imsgtcar@@mathfs.math.montana.edu>}, +Michelangelo Grigni @samp{<mic@@cs.ucsd.edu>}, +Manoj Srivastava @samp{<srivasta@@pilgrim.umass.edu>}, +Richard Stanton @samp{<stanton@@haas.berkeley.edu>}, +Kobayashi Shinji @samp{<koba@@flab.fujitsu.co.jp>}, +and probably more.@refill + +@itemize @bullet +@item +@LaTeX{}2e is now default. Set @code{LaTeX-version} to @samp{"2"} to +disable this. + +@item +Better handling of @samp{*TeX background*} buffer. Suggested by John +Interrante @samp{<interran@@uluru.Stanford.EDU>}. + +@item +Parser did not recognise the use of @samp{\def} to create @LaTeX{} +environments. Reported by Frederic Devernay +@samp{<Frederic.Devernay@@sophia.inria.fr>}. + +@item +Minor cleanup in some error messages. + +@item +Fixed bug in @code{TeX-comment-paragraph} when called with a negative +argument. Reported by Markus Kramer @samp{<kramer@@inf.fu-berlin.de>}. + +@item +Don't move point in master file when running a command on the region in +an included file. Thanks to Karl Wilhelm Langenberger +@samp{<wlang@@rs6000.mri.akh-wien.ac.at>} for the patch. + +@item +@code{LaTeX-math-mode} no longer works on Emacs 18 or older Lucid +versions. This change allowed me to unbundle @file{min-map.el}. + +@item +Made @kbd{C-c C-e} more robust, especially when applied on an empty +active region. Reported by Andrew Senior @samp{<aws@@eng.cam.ac.uk>}. + +@item +@kbd{C-c C-m section RET} and @kbd{M-@key{tab}} should work now in +@TeX{}info mode. @kbd{C-c C-b} and @kbd{C-c C-r} removed, since they +did not work. Reported by Karl Eichwalder +@samp{<karl@@pertron.central.de>}. + +@item +Made @kbd{M-q} skip block comments. Sugested by Peter Whaite +@samp{<peta@@cim.mcgill.ca>}. + +@item +Code cleanup: Renamed @samp{-format-} functions to @samp{-fill-}. + +@item +Made @kbd{,} and @kbd{.} remove any preceding italic correction. + +@item +Changes in math mode: @samp{setminus} moved to @key{\}, @samp{not} moved +to @key{/}, and @samp{wedge}, @samp{vee}, and @samp{neg} installed on +@key{&}, @kbd{|}, and @kbd{!} to make writing logic easier for C +programmers. + +@item +Renamed @file{auc-tex.el} to @file{auc-old.el} to make it less likely +that new users load it by mistake. + +@item +Changed name of @file{easymenu.el} to @file{auc-menu.el} to avoid +conflict with RMS's version. Updated it to handle the Lucid +@code{:keys} keyword argument. Defines a popup menu for both FSF and +Lucid emacs, although it is only installed in Lucid Emacs. Added David +Aspinall's @samp{<da@@dcs.edinburgh.ac.uk>} patch to handle an empty +menu bar under Lucid Emacs. The interface is still a superset of +@file{easymenu.el}. This version should no longer prevent the sharing +of byte compiled files between FSF and Lucid emacs. + +@item +Marking a section or environment now highlight it in Lucid Emacs. It +already worked in GNU Emacs. Thanks to Andreas Ernst +@samp{ernst_a@@maths.uwa.edu.au}. + +@item +Font support for @LaTeX{}2e. Many people suggested this. +Automatically activated for all documents defined with +@samp{\documentclass}. + +@item +Outline support for @LaTeX{}2e fixed by Robert Estes +@samp{<estes@@ece.ucdavis.edu>}. + +@item +@samp{bibliography} macro now works. Thanks to Frederic Devernay +@samp{<Frederic.Devernay@@sophia.inria.fr>}. + +@item +Fixes to @file{psfig} support by Thomas Graichen +@samp{<graichen@@sirius.physik.fu-berlin.de>}. + +@item +Fixed position of @samp{\label} in environments. Reported by Richard +Stanton @samp{<stanton@@haas.berkeley.edu>}. + +@item +Made the name of the AUC @TeX{} menu mode specific. + +@item +More reliable guesses with @kbd{C-c C-r}. Thanks to Lawrence R. Dodd +@samp{<dodd@@roebling.poly.edu>}. + +@item +Insert newline before inserting local variable section. Thanks to +Rajeev Gore' @samp{<rpg@@cs.man.ac.uk>}. + +@item +Fixes to Japanese version. Thanks to Kobayashi Shinji +@samp{<koba@@flab.fujitsu.co.jp>}. + +@item +Fixed bug in @samp{put} and @samp{multiput} macros. Thanks to Kobayashi +Shinji @samp{<koba@@flab.fujitsu.co.jp>} and Masayuki Kuwada +<kuwada@@axion-gw.ee.uec.ac.jp>. + +@item +Display number of pages after end of @LaTeX{} compilation. Thanks to +Lawrence R. Dodd @samp{<dodd@@roebling.poly.edu>}. + +@item +Only update section and environment menus when the lists have changed. + +@item +New variables @code{LaTeX-header-end} and @code{LaTeX-trailer-start}. + +@item +Some Emacs 18 compatibility changes. Thanks to Fran E. Burstall +@samp{<F.E.Burstall@@maths.bath.ac.uk>}. + +@item +Use nonrecursive function to determine the current environment. This +should solve problems with exceeding lisp max depth. Contributed by +David Aspinall @samp{<da@@dcs.edinburgh.ac.uk>}. + +@item +Fixed documentation for @kbd{` ~} in @file{math-ref.tex}. Thanks to +Morten Welinder @samp{<terra@@diku.dk>}. + +@item +Made @code{LaTeX-math-mode} work better with FSF Emacs 19 in the case +where you press something undefined, in particular function keys. +Requested by several. + +@item +Inserting an itemize environment around the active region now insert the +first item inside the environment. Thanks to Berwin A. Turlach +@samp{<berwin@@core.ucl.ac.be>} for reporting this. + +@item +Fixed bug in right button menu under Lucid. Reported by Frederic +Devernay @samp{<Frederic.Devernay@@sophia.inria.fr>}. +@end itemize + +@node Version 9.0 +@section News in 9.0 + +Coordinator: Per Abrahamsen, 1994. + +Alpha testers (in order of appearance): +Volker Dobler @samp{<dobler@@etu.wiwi.uni-karlsruhe.de>}, +Piet van Oostrum @samp{<piet@@cs.ruu.nl>}, +Frederic Devernay @samp{<Frederic.Devernay@@sophia.inria.fr>}, +Robert Estes @samp{<estes@@ece.ucdavis.edu>}, +Berwin Turlach @samp{<berwin@@core.ucl.ac.be>}, +Tim Carlson @samp{<imsgtcar@@mathfs.math.montana.edu>}, +Peter Thiemann @samp{<thiemann@@provence.informatik.uni-tuebingen.de>}, +Kevin Scott @samp{<scottkj@@prl.philips.co.uk>}, +Lawrence R. Dodd @samp{<dodd@@roebling.poly.edu>}, +Johan Van Biesen @samp{<vbiesen@@wins.uia.ac.be>}, +Marc Gemis @samp{<makke@@wins.uia.ac.be>}, +Michelangelo Grigni @samp{<mic@@cs.ucsd.edu>}, +Kevin Scott @samp{<scottkj@@prl.philips.co.uk>}, +Peter Paris @samp{<pparis@@bass.gmu.edu>}, +Peter Barth @samp{<barth@@mpi-sb.mpg.de>}, +Andy Piper @samp{<ajp@@eng.cam.ac.uk>}, +Richard Stanton @samp{<stanton@@haas.berkeley.edu>}, +Christoph Wedler @samp{<wedler@@fmi.uni-passau.de>}, +Graham Gough @samp{<graham@@cs.man.ac.uk>}, +and probably more.@refill + +@itemize @bullet +@item +Fixed problem with @file{filladapt} defeating @LaTeX{} mode's own +indentation algorithm. Thanks to Piet van Oostrum +@samp{<piet@@cs.ruu.nl>}. + +@item +Made environments and sections selectable from the menu bar. + +@item +Support Emacs comment conventions. Comments starting with a single +@samp{%} are indented at @code{comment-column}. Comments starting with +@samp{%%%} are indented at column 0. Comments starting with +@samp{%%} are indented like ordinary text. You can set the variables +@code{LaTeX-right-comment-regexp} and @code{LaTeX-left-comment-regexp} +to nil to disable this. See also @code{LaTeX-ignore-comment-regexp}. +Rewrote it from Christoph Wedler @samp{<wedler@@fmi.uni-passau.de>} from +original code. + +@item +@key{tab} and @key{lfd} will not indent code in @samp{verbatim} +environment if you set @code{LaTeX-indent-environment-check} to non-nil. +This was also first implemented by Christoph Wedler +@samp{<wedler@@fmi.uni-passau.de>}. + +@item +You can now get get custom indentation for various environments. See +@code{LaTeX-indent-environment-list}. + +@item +@kbd{C-c C-m left @key{ret}} new automatically inserts a matching +@samp{\right}. See variables @code{TeX-left-right-braces}, +@code{TeX-braces-default-association}, and +@code{TeX-braces-user-association}. This feature was suggested by Jesse +@samp{<jes@@math.msu.edu>} and implemented by Berwin Turlach +@samp{<berwin@@core.ucl.ac.be>}. + +@item +Don't automatically display the compilation buffer unless +@code{TeX-show-compilation} in non-nil. Suggested by Stefan Schoef +@samp{Stefan.Schoef@@arbi.informatik.uni-oldenburg.de}. + +@item +Bundled @file{ltx-help.el}. Press @kbd{C-h C-l} to get the +documentation for a LaTeX command. + +@item +Fixed indentation of @samp{\left} and @samp{\right}. Thanks to +Christoph Wedler @samp{<wedler@@fmi.uni-passau.de>}. + +@item +Installation procedure changed. @file{tex-site.el} is now intended to +survive AUC @TeX{} upgraded. The distribution version only contains +autoloads (eliminating the need for @file{tex-load.el} , the +customization variables are moved to @file{tex.el}. You should copy +those variables you need to customize from @file{tex.el} to +@file{tex-site.el}. + +@item +Made it possible to use absolute paths when including bibliographies or +style files. + +@item +Fixed problem with parsing errors after running @LaTeX{} on the region +from the menu. Thanks to Peter Barth @samp{<barth@@mpi-sb.mpg.de>} for +finding this one. + +@item +The file @file{doc/ref-card.texi} has been renamed to +@file{doc/tex-ref.texi} to avoid confusion with the reference card for +GNU Emacs. Suggested by Michelangelo Grigni @samp{<mic@@cs.ucsd.edu>}. + +@item +The @file{README}, @file{CHANGES} and @file{INSTALLATION} files are now +generated from chapters of this manual, to ensure they stay in sync. + +@item +@kbd{M-@key{tab}} will now complete some macro arguments in addition to +macro names. In particular, if you press @kbd{M-@key{tab}} after +@samp{\cite@{} or @samp{\ref@{} you will get completion for bibitems and +labels, respectively. + +@item +Merged a number of files. The major files are now @file{tex.el} for +plain @TeX{} and common support, @file{tex-buf.el} for running external +commands, and @file{latex.el} for @LaTeX{} support. + +@item +Unbundled @file{outln-18.el}. Users of Emacs 18 or Lucid Emacs 19.9 or +earlier must get @file{outln-18.el} and install it as @file{outline.el} +if they want the outline commands to work. + +@item +No longer bind @kbd{C-c @key{tab}} to @code{TeX-complete-symbol}. Use +@kbd{M-@key{tab}} instead. + +@item +Cleaned up the parser and parameterizedd it. Now you can add now types +of information to be maintained by the parser simply by calling +@code{TeX-auto-add-type}. You still need to install the regexps with +@code{TeX-auto-add-regexp}. + +@item +Disable the automatic insertion of empty braces after macros with no +arguments in @code{LaTeX-math-mode}. Added a variable +@code{TeX-insert-braces} to disable it everywhere. + +@item +Now complete with existing labels when asking for a label in a @LaTeX{} +environment. Suggested by Berwin Turlach +@samp{<berwin@@core.ucl.ac.be>}. + +@item +The variables @code{TeX-private-macro}, @code{TeX-private-auto}, and +@code{TeX-private-style} are now initialized from the @samp{TEXINPUTS} +and @samp{BIBINPUTS} environment variables. + +@item +@kbd{C-c C-f} and @kbd{C-c C-e} will now put the template around the +region if the region is active. + +@item +Fixed @kbd{C-u C-c C-e} to handle environments ending with a star +(@samp{*}). Reported by Berwin Turlach +@samp{<berwin@@core.ucl.ac.be>}. + +@item +Don't use @code{with-output-to-temp-buffer} for compilation buffer. +Fixed by Frederic Devernay @samp{<Frederic.Devernay@@sophia.inria.fr>}. + +@item +New function @code{TeX-command-buffer} (@kbd{C-c C-b}) to run a command +on the (visible part of) the current buffer. Requested by several +people. + +@item +Bundled the latest @file{reporter.el}, added +@code{TeX-submit-bug-report} to menus. + +@item +@code{TeX-insert-braces} now takes an argument like +@code{insert-parentheses}. Thanks to Lawrence R. Dodd +@samp{<dodd@@roebling.poly.edu>}. + +@item +Fixed bug in @samp{\put} and @samp{\multiput} macros. Thanks to Kevin +Scott @samp{<scottkj@@prl.philips.co.uk>}. + +@item +Deleted @code{ams-latex-mode}, @code{slitex-mode}, and +@code{foiltex-mode}. Instead, use @code{LaTeX-command-style} to +determine the name of the external command to use. + +@item +Deleted @code{latex2e-mode}. Instead set the @code{LaTeX-version} +variable. This may be done automatically if you use +@samp{\documentclass} in the future. + +@item +Fixed Lucid Emacs menu for @TeX{}info mode. Thanks to Frederic Devernay +@samp{<Frederic.Devernay@@sophia.inria.fr>}, + +@item +Added support for @file{harvard.sty} by Berwin Turlach +@samp{<berwin@@core.ucl.ac.be>}. + +@item +Filling will not let display math equations @samp{\[ ... \]} be on a +line by themselves. Reported by Matthew Morley +@samp{<Matthew.Morley@@gmd.de>}. + +@item +Made @code{words-include-escapes} default to nil. + +@item +Made @code{TeX-expand-list} expansions case sensitive. Thanks to Havard +Rue @samp{<Havard.Rue@@sima.sintef.no>}. + +@item +Fixed error in calculating indentation for lines starting with a brace. +Thanks to Piet van Oostrum @samp{<piet@@cs.ruu.nl>}. + +@item +Fixed bug in the @samp{addcontentsline}, @samp{newtheorem}, and +@samp{pagenumbering} macros reported by Berwin Turlach +@samp{<berwin@@core.ucl.ac.be>}. + +@item +Doc fixes by Lawrence R. Dodd @samp{<dodd@@roebling.poly.edu>}. + +@item +Indentation no longer fooled by @samp{\\@{}, Thanks to Peter Thiemann +@samp{<thiemann@@provence.informatik.uni-tuebingen.de>}. + +@item +Bind @kbd{M-C-e} and @kbd{M-c-a} to @code{LaTeX-find-matching-end} and +@code{LaTeX-find-matching-begin}. Suggested by Lawrence R. Dodd +@samp{<dodd@@roebling.poly.edu>}. + +@item +Added variable @code{TeX-quote-after-quote} which causes +@code{TeX-insert-quote} to insert literal @samp{"} except when after +another @samp{"}, in which case it will expand to @code{TeX-open-quote} +or @code{TeX-close-quote}. This code was contributed by Piotr Filip +Sawicki @samp{<pfs@@mimuw.edu.pl>}. + +@item +Added support for Polish style files @file{plfonts.sty} and +@file{plhb.sty}, contributed by Piotr Filip +Sawicki @samp{<pfs@@mimuw.edu.pl>}. + +@item +Added section with suggestions for how to handle European +character sets. + +@item +Created workaround for bug in the regexp handler in some Emacs 18 +versions and older versions of Lucid Emacs. The workaround +means you cannot use space in the documentstyle command in Emacs and +Lucid Emacs earlier than version 19.9. + +@item +@file{powerkey.el} is removed since the functionality is integrated in +GNU Emacs + +@item +@kbd{C-u "} now inserts four literal @samp{"}, not just one. To insert +a single @samp{"} either press @key{"} twice or use @kbd{C-q "}. + +@item +Allow non-string value for @code{outline-minor-map-prefix}. Reported by +David Smith @samp{<maa507@@comp.lancs.ac.uk>}. + +@item +Make the use of @code{write-file-hooks} more safe, and use +@code{local-write-file-hooks} when possible. Suggested by David Smith +@samp{<maa507@@comp.lancs.ac.uk>}. + +@item +Don't indent @samp{\begin@{verbatim@}} and @samp{\end@{verbatim@}}, +since any space before @samp{\end@{verbatim@}} is significant. Thanks to +Peter Thiemann @samp{<thiemann@@informatik.uni-tuebingen.de>} for the +patch. + +@item +Show available fonts when you try to insert an non-existing font. +Suggested by David Smith @samp{<maa507@@comp.lancs.ac.uk>}. + +@item +The @code{member} function in @file{tex-18.el} does not depend on +@code{TeX-member} now. Thanks to Piet van Oostrum +@samp{<piet@@cs.ruu.nl>}. + +@item +Do not overwrite any global binding of @kbd{M-@kbd{ret}}. Suggested by +Jens Petersen @samp{<J.Petersen@@qmw.ac.uk>}. + +@item +Major modes for writing text are supposed to rebind @kbd{M-@kbd{tab}} to +@code{ispell-complete-word}. Reported by Jens Petersen +@samp{<J.Petersen@@qmw.ac.uk>}. + +@item +Fixed problems with @TeX{}info menus. Thanks to David Smith +@samp{<maa507@@comp.lancs.ac.uk>} for reporting this. + +@item +Code cleanup. Removed the @file{format} directory, as it did not make +it easier to add new @TeX{} modes, quite the contrary. + +@item +Fixed name conflict in @file{auc-tex.el}, reported by Rik Faith +@samp{<faith@@cs.unc.edu>}. + +@item +Fixed some spelling errors. Thanks to Lawrence R. Dodd +@samp{<dodd@@roebling.poly.edu>}. + +@item +Fixed bug prohibiting non-standard file extensions. Now recognize +@file{.ltx} by default. Suggested by Lawrence R. Dodd +@samp{<dodd@@roebling.poly.edu>}. + +@item +Name of the AUC @TeX{} info files changes once again to be usable under +DOS. This time simply to @file{auctex}. + +@item +Documented @code{TeX-outline-extra}. + +@item +Could not select command on region from the menu before loading +@file{tex-buf}. Reported by Uwe Bonnes +@samp{<bon@@lte.e-technik.uni-erlangen.de>}. + +@item +Make the hilit19 interface more robust. Thanks to William Dean Norris +II @samp{<wdn@@dragonfly.cis.ufl.edu>}. + +@item +More OS/2 Makefile fixes by Bodo Huckestein +@samp{<bodo@@eu10.mpi-hd.mpg.de>}. + +@item +Reimplemented comment support on top of @code{comment-region}, giving +slightly different semantics. +@end itemize + + +@node Version 8.0 +@comment node-name, next, previous, up +@section News in 8.0 + +Coordinator: Per Abrahamsen, 1993. + +Alpha testers (in order of appearance): Marc Gemis +@samp{<makke@@wins.uia.ac.be>}, Shinji Kobayashi +@samp{<koba@@flab.fujitsu.co.jp>}, Philippe Defert +@samp{<defert@@gnuisance.cern.ch>}, Richard Stanton +@samp{<stanton@@haas.berkeley.edu>}, Norbert Kiesel +@samp{<norbert@@i3.informatik.rwth-aachen.de>}, Roberto Cecchini +@samp{<CECCHINI@@fi.infn.it>}, Hanno Wirth @samp{<wirth@@igd.fhg.de>}, +Tim Carlson @samp{<tim@@math.montana.edu>}, John Daschbach +@samp{<dasch@@darkwing.uoregon.edu>}, Bob Fields +@samp{<bob@@minster.york.ac.uk>}, Peter Whaite +@samp{<peta@@cim.mcgill.ca>}, Volker Dobler +@samp{<dobler@@etu.wiwi.uni-karlsruhe.de>}, Phil Austin +@samp{<phil@@geog.ubc.ca>}, Martin Maechler +@samp{<maechler@@stat.math.ethz.ch>}, Havard Rue +@samp{<Havard.Rue@@sima.sintef.no>}, Tim Geisler +@samp{<tmgeisle@@faui80.informatik.uni-erlangen.de>}, Tim Carlson +@samp{<imsgtcar@@mathfs.math.montana.edu>}, Sridhar Anandakrishnan +@samp{<sak@@essc.psu.edu>}, Peter Thiemann +@samp{<thiemann@@provence.informatik.uni-tuebingen.de>}, Pedro Quaresma +@samp{<pedro@@mat.uc.pt>}, Christian Lynbech +@samp{<lynbech@@daimi.aau.dk>}, Kevin Scott +@samp{<scottkj@@prl.philips.co.uk>}, Bodo Huckestein +@samp{<bodo@@eu10.mpi-hd.mpg.de>}, Cengiz Alaettinoglu +@samp{<ca@@cs.UMD.EDU>}, Jakob Schiotz +@samp{<schiotz@@fysik.dth.dk>}, and probably more.@refill + +@itemize @bullet +@item +New variable @code{LaTeX-letter-sender-address} contains default address +for use with the letter style. Set it to the address of your +organization in @file{tex-site.el}. Thanks to Sridhar Anandakrishnan +@samp{<sak@@essc.psu.edu>}. + +@item +Makefile now works under OS/2 with GNU Make. Thanks to Bodo Huckestein +@samp{bodo@@eu10.mpi-hd.mpg.de}. + +@item +Made it possible to install global auto files without having Bib@TeX{} +mode installed. Thanks to Christian Lynbech +@samp{<lynbech@@daimi.aau.dk>}. + +@item +Minor documentation fixes. Thanks to Martin Maechler +@samp{<maechler@@stat.math.ethz.ch>}. + +@item +Added support for @samp{eqref} for the @samp{amsart} style. Thanks to +Peter Whaite @samp{<peta@@cim.mcgill.ca>}. + +@item +Use @samp{-c} as the default shell command option under @samp{emx}. +Eberhard Mattes @samp{<mattes@@azu.informatik.uni-stuttgart.de>} says +it is better than @samp{/c}. + +@item +Made powerkey in the menus work better under OS/2. Thanks to Eberhard +Mattes @samp{<mattes@@azu.informatik.uni-stuttgart.de>}. + +@item +Made the reference cards print correctly on US letter format paper. +Thanks to Magnus Nordborg @samp{<magnus@@fisher.Stanford.EDU>}. + +@item +@code{LaTeX-dead-mode} removed. Read the file `ISO-TEX' for alternative +solutions. + +@item +All minor modes unbundled. You can find them from ftp at +@samp{ftp.iesd.auc.dk} in the directory @file{/pub/emacs-lisp}. Removed +information about minor modes from this document. + +@item +New hooks for changing ispell directory, see @file{tex-site.el} for +details. + +@item +@LaTeX{}2e mode now supported. Insert + +@lisp + (setq TeX-default-mode 'latex2e-mode) +@end lisp + +in your @file{.emacs} file to get documentclass instead of documentstyle +per default. The parser recognizes documentclass, usepackage, and +newcommand with a default argument. There are also templates for all of +them. + +@item +Added Jakob Schiotz's @samp{<schiotz@@fysik.dth.dk>} help file for +installing AUC @TeX{} on OEMACS. It will probably also be of interest +for DEMACS users. + +@item +Minor changes to be more friendly for OEMACS, thanks to Jakob Schiotz +@samp{<schiotz@@fysik.dth.dk>}. + +@item +The control key bindings in @code{LaTeX-math-mode} now works, thanks to +Frederic Devernay @samp{<Frederic.Devernay@@sophia.inria.fr>}. + +@item +@LaTeX{} outlines no longer matches @samp{\partial} or other commands +with a sectioning command as prefix. Thanks to Jakob Schiotz +@samp{<schiotz@@fysik.dth.dk>}. + +@item +@code{LaTeX-fill-paragraph} now handles the case where the previous line +both contain an @samp{\item} and an unmatched open brace. Thanks to +Piet van Oostrum @samp{<piet@@cs.ruu.nl>}. + +@item +Use abbreviated file name for @TeX{} output buffers in Emacs 19. Thanks +to Jens Gustedt @samp{<gustedt@@math.tu-berlin.de>}. + +@item +Added lowercase alias for @code{LaTeX-math-mode} for use with Emacs file +mode commands. Thanks to Olaf Burkart +@samp{<burkart@@zeus.informatik.rwth-aachen.de>}. + +@item +Added code to reuse old region in @code{TeX-command-region} if mark is +not active. Thanks to Cengiz Alaettinoglu @samp{<ca@@cs.UMD.EDU>}. + +@item +Now get keyboard accelerators on all menus rather than only AUC @TeX{} +menus, thanks to the @file{powerkey.el} file by Lars Lindberg +@samp{<lli@@sypro.cap.se>}. + +@item +Added @code{TeX-electric-macro} for faster completion of @TeX{} macros. +@xref{Completion}. + +@item +Comparing printer names are now case incentive. Thanks to Richard +Stanton @samp{<stanton@@haas.berkeley.edu>}. + +@item +Default shell fixed for OS/2. Thanks to Richard Stanton +@samp{<stanton@@haas.berkeley.edu>}. + +@item +Added functions to hide (@code{LaTeX-hide-environment}) and show +(@code{LaTeX-show-environment}) the current environment. + +@item +@kbd{C-u C-c C-e} will now modify the current environment instead of +inserting a new environment. This is like the optional argument to the +font commands. + +@item +Added nabla to LaTeX Math Mode. Suggested by Bill Reynolds +@samp{<bill@@goshawk.lanl.gov>}. + +@item +Added commands for running @TeX{} and @LaTeX{} interactively. Thanks to +David Carlisle @samp{<carlisle@@computer-science.manchester.ac.uk>}. + +@item +The external commands will now insert there output @emph{before} point +in the output buffers. This allows you to follow the progress by +putting point at the end of the file. Suggested by Jak Kirman +@samp{<jak@@cs.brown.edu>}. + +@item +When invoking an external command from a menu, the document will be +automatically saved. + +@item +There are now a printer menu for emacs 19. + +@item +Redesigned dependency checking. Now only checks dependencies for files +loaded in the current emacs session. This is much faster, but will not +catch files that are edited outside this emacs session, or files edited +in killed buffers. @strong{@code{TeX-check-path} must at least contain +@file{.} for saving to work}. If you have set @samp{TeX-check-path} +in your @file{.emacs} file, remove it. The default value is fast enough +now. + +@item +New variable @code{TeX-save-query} control if AUC @TeX{} will query you +for each modified buffer when you save the document. Set it to nil to +get rid of these questions. Setting this variable also affect the +automatic saving of the document that happens each time you start an +external command. + +@item +New command @code{TeX-save-document} will save all files in the current +document, i.e. the document associated with the current buffer. + +@item +Cleaned up all minor modes, also made them use @file{min-map.el} or +@file{min-mode.el} instead of @file{min-bind.el}. + +@item +Cleaned up release management. + +@item +AUC TeX will not longer be confused when you rewrite a file under a new +name. + +@item +Lots of code cleanup, involving reformatting the source and renaming all +@samp{-hook} variables and functions to conform with the Emacs 19 +guidelines. + +@item +Can now parse Japanese characters in labels and macros when you use +Japanese @TeX{}. Thanks to Shinji Kobayashi +@samp{<koba@@flab.fujitsu.co.jp>}. + +@item +Made it safe to quit when AUC @TeX{} asks for the name of the master +file. It will simply assume the file itself is the master, and continue +without inserting any file local variables. + +@item +Support for @code{epsf} and @code{psfig} style files. Thanks to Marc +Gemis @samp{<makke@@wins.uia.ac.be>}. + +@item +Support for @LaTeX{}info. Thanks to Marc Gemis +@samp{<makke@@wins.uia.ac.be>}. + +@item +Only examine the first 10000 bytes to find out what @TeX{} mode to use. + +@item +Added @code{TeX-submit-bug-report} command to submit bug reports. It +uses the @file{reporter.el} distributed with SuperCite, so it may not be +available in some Emacs 18 installations. + +@item +Speeded up parsing significantly by using a simpler regexp. + +@item +Added variable @code{TeX-auto-untabify}. Set it to nil to prevent +untabifying the buffer when it is saved. Several people wanted this. + +@item +Changed defaults to @emph{not} do any automatic parsing, nor prompt for +a master file. @xref{Parsing Files}, @ref{Multifile}, for information +about how ot correct this. In short, insert the following in your +@file{.emacs} file. + +@lisp +(setq TeX-auto-save t) +(setq TeX-parse-self t) +(setq-default TeX-master nil) +@end lisp + +@item +Some grammatical fixes to the @file{PROBLEMS} file. Thanks to Lawrence +R. Dodd @samp{<dodd@@roebling.poly.edu>}. + +@item +No longer install a separate @code{outline-minor-mode} by default, as +the FSF Emacs 19.19 @code{outline-minor-mode} is adequate. The included +file @file{outln-18.el} emulates the FSF Emacs 19.19 mode under Emacs 18. + +The FSF Emacs 19.19 @code{outline-minor-mode} use the @kbd{C-c} prefix +instead of @kbd{C-c C-o} by default, and does not bind as many keys as +the @code{outline-minor-mode} distributed with earlier versions of AUC +@TeX{} did. You can get the keybindings back together with other +goodies by inserting +@example +(require 'out-xtra) +@end example +in your @file{.emacs} file. @file{out-xtra.el} will probably be +unbundled from AUC @TeX{} in the future. + +@item +Some fixes to AmS-@TeX{} mode by Ulf Juergens +@samp{<ulf@@mathematik.uni-bielefeld.de>}. + +@item +Make @samp{plain-TeX-mode-menu} work in Lucid Emacs. Thanks to Anthony +Rossini @samp{rossini@@hsph.harvard.edu} for reporting this. + +@item +First cut on a @TeX{}info mode. + +@item +More strict about parsing @samp{\bibitem}'s and Bib@TeX{} entries. + +@item +Made it easier to write style files for environments that takes +arguments and documented it. Suggested by Martin +Wunderli @samp{<wunderli@@inf.ethz.ch>}. + +@item +Parse optional argument to @samp{\newenvironment}. Suggested by Martin +Wunderli @samp{<wunderli@@inf.ethz.ch>}. + +@item +Fixed @samp{parbox} macro. Thanks to Shinji Kobayashi +@samp{<koba@@flab.fujitsu.co.jp>}. + +@item +Made the parser work better in outline minor mode. Thanks to Salvador +Pinto Abreu @samp{<spa@@khosta.fct.unl.pt>}. + +@item +Also save style information with @code{TeX-normal-mode} when buffer not +modified. + +@item +Use @code{$(MAKE)} instead of @samp{make} to invoke @code{make} from the +@file{Makefile}. Thanks to John Interrante +@samp{<interran@@uluru.Stanford.EDU>}. + +@item +Make last value default for @code{TeX-insert-macro}. Suggested by Matt +Fairtlough @samp{<M.Fairtlough@@dcs.sheffield.ac.uk>}. + +@item +Renamed info file to @samp{auc-info} in order to fill DOS file limits. +Please remember to update your @file{dir} file to reflect this change. + +@item +Delete auto file instead of saving an empty file. +@end itemize + +@node Version 7.3 +@comment node-name, next, previous, up +@section News in 7.3 + +Coordinator: Per Abrahamsen, 1993. + +@itemize @bullet +@item +More robust installation, especially for Lucid Emacs (I hope). Many +people reported problems with this. + +@item +Make `easymenu' work when byte-compiled. Many people reported this +bug. + +@item +Minimally updated the @file{README} file from version 6.0 (sigh). +Thanks to Boris Goldowsky @samp{<boris@@cs.rochester.edu>} for reporting +this. + +@item +Added @samp{@@finalout} to manual. Reported by Henrik Drabol +@samp{<hvd@@ens004.ens.min.dk>}. + +@item +Fixed @kbd{M-q} to work after an @samp{\end@{@dots{}@}}. It will not +work at the end of the buffer, but there are usually the local variables +so it should (hopefully) not matter. Thanks to Shinji Kobayashi +@samp{<koba@@flab.fujitsu.co.jp>} again. + +@item +New variables @code{TeX-open-quote} and @code{TeX-close-quote} determine +what is inserted by @code{TeX-insert-quote}. The @file{german} style +file now use those variables instead of changing the keymap. + +@item +Changes to the default settings in @file{tex-site.el}, in particular a +@samp{Queue} command is added to display the print queue. Thanks to +John Interrante @samp{<interran@@uluru.Stanford.EDU>} for code, and +other members of the @samp{auc-tex@@iesd.auc.dk} mailing list for +ideas. + +@item +Make sure all outline mode commands are bound in +@code{outline-minor-mode}. + +@item +Added autoload for @code{TeX-command}. Thanks to Hanno Wirth +@samp{<wirth@@igd.fhg.de>} for reporting this. + +@item +Added support for AmS@TeX{} and AmSLa@TeX{}. Currently they are +identical to @TeX{} and @LaTeX{} except for another default command. + +@item +Added Vor@TeX{} style matching of dollar sign. The style is guaranteed +to be Vor@TeX{}, since I lifted the code directly from Vor@TeX{}. +Thanks to Pehong Chen @samp{<phc@@renoir.berkeley.edu>} for writing the +Vor@TeX{} code. Thanks to Jak Kirman @samp{<jak@@cs.brown.edu>} for +pointing out this nice Vor@TeX{} feature. + +@item +Added information about AUC @TeX{} mail addresses to the manual. Thanks +to Dave Smith @samp{<maa507@@computing.lancaster.ac.uk>}. + +@item +Added menu to for plain @TeX{}. Suggested by Tim Carlson +@samp{<imsgtcar@@math.montana.edu>}. + +@item +Made the menus depend on @code{TeX-command-list}. + +@item +Made it possible to specify @code{TeX-auto-regexp-list} in the local +variable section of each file. + +@item +Added variable @code{TeX-auto-parse-length} to specify maximal length of +text that will be parsed. + +@item +Added automatic parsing of Bib@TeX{} files and @samp{bibitem} entries in +order to get completion in @samp{cite}. This was inspired by an add on +made by Sridhar Anandakrishnan @samp{<sak@@essc.psu.edu>}. + +@item +Added variable @code{TeX-byte-compile} to disable automatic byte +compilation of style files when loaded. This is needed when using +different Emacs versions. + +@item +Added variable @code{TeX-translate-location-hook} to translate file and +line information before showing an error, as requested by Thorbjoern +Ravn Andersen @samp{<ravn@@imada.ou.dk>}. + +@item +Added variable @code{TeX-auto-save} to allow disabling the automatic +saving of style information, either per file in the file local +variables, or globally by using @code{setq-default}. Use +@code{TeX-normal-mode} to force style information to be saved. + +@item +Try to create @file{auto} directory if it does not exists. + +@item +Added chapter describing how to tune the @TeX{} parsing. + +@item +Allow (but do not encourage) a string value for +@code{LaTeX-default-options}. + +@item +Give @samp{"} word syntax when german.sty is loaded. Suggested by Tim +Geisler @samp{<tmgeisle@@immd8.informatik.uni-erlangen.de>}. + +@item +Many corrections to the grammar in the manual. Thanks to Manfred +Weichel @samp{<Manfred.Weichel@@sto.mchp.sni.de>}. + +@item +Bind @code{TeX-home-buffer} to @kbd{C-c ^} instead of @kbd{C-c C-h} +which are reserved in Emacs 19. Suggested by Chris Moore +@samp{<Chris.Moore@@src.bae.co.uk>}. +@end itemize + +@node Version 7.2 +@comment node-name, next, previous, up +@section News in 7.2 + +Coordinator: Per Abrahamsen, 1993. + +@itemize @bullet +@item +@code{LaTeX-dead-mode} works again. Thanks to Patrick O'Callaghan +@samp{<poc@@usb.ve>} for fixing it. + +@item +Minor fixes to the documentation. Thanks to Shinji Kobayashi +@samp{<koba@@flab.fujitsu.co.jp>}. + +@item +Add @samp{Compiling} to the mode line of all buffers, while there is a +AUC @TeX{} compilation process running. This is similar to the behavior +of @code{compile} in Emacs 19. + +@item +@code{TeX-normal-mode} will now save the buffer first to make sure it +gets reparsed. + +@item +Labels with underscores are now recognized. Thanks to Wolfgang Franzki +@samp{<W.Franzki@@kfa-juelich.de>} + +@item +Fix to `ghostview' printer specification. Thanks to Masayuki Kuwada +@samp{<kuwada@@soliton.ee.uec.ac.jp>}. + +@item +Recognize @samp{abstract}, @samp{center}, @samp{titlepage}, +@samp{verse}, and @samp{theindex} environments. Thanks to Masayuki Kuwada +@samp{<kuwada@@soliton.ee.uec.ac.jp>}. + +@item +Fix to @samp{newsavebox} macro. Thanks to Shinji Kobayashi +@samp{<koba@@flab.fujitsu.co.jp>} for reporting this. + +@item +Menu support for GNU Emacs 19 and Lucid Emacs. Thanks to Alastair Burt +@samp{<burt@@dfki.uni-kl.de>} for the initial Lucid Emacs version. + +@item +@kbd{C-c C-f C-d} now deletes the current font. The current font is +defined to be the innermost @TeX{} group starting with a @TeX{} macro +that is terminated by a space. + +@item +Giving @kbd{C-c C-f} a prefix argument will replace the current font, +i.e. @kbd{C-u C-c C-f C-b} will change the current font to bold. + +The old functionality (putting the font around the region) has been +removed. To make the region bold, type @kbd{C-w C-c C-f C-b C-y} +instead. + +@item +Chapter recognized as largest heading in the report style. Thanks to +Shinji Kobayashi @samp{<koba@@flab.fujitsu.co.jp>} for reporting +this. + +@item +More support for Japanese style files. Thanks to Shinji Kobayashi +@samp{<koba@@flab.fujitsu.co.jp>}. + +@item +No longer put @samp{Outline} in the mode line whenever +@code{selective-display} is set. Thanks to Lawrence R. Dodd +@samp{<dodd@@roebling.poly.edu>} for reporting this. + +@item +Support for inserting calligraphic letters in @code{TeX-math-mode} with +@kbd{` c @key{letter}}. Thanks to Olaf Burkart +@samp{<burkart@@zeus.informatik.rwth-aachen.de>}. + +@item +@code{set-docstring} in @file{tex-math.el} should work better now. +Thanks to Alastair Burt @samp{<burt@@dfki.uni-kl.de>} and Olaf Burkart +@samp{<burkart@@zeus.informatik.rwth-aachen.de>}. + +@item +Support for dviout preview on PC-9801. Thanks to Shinji Kobayashi +@samp{<koba@@flab.fujitsu.co.jp>}. + +@item +Inserting environment in empty buffer should work now. Thanks to +Alastair Burt @samp{<burt@@dfki.uni-kl.de>}. + +@item +Default float for figures changed from @samp{tbp} to @samp{htbp}. + +@item +@code{LaTeX-format-environment} may work now. Thanks to Shinji +Kobayashi @samp{<koba@@flab.fujitsu.co.jp>}. + +@item +Better @code{LaTeX-close-environment}. Thanks to Thorbjoern Hansen +@samp{<thansen@@diku.dk>}. + +@item +Some support for Ispell 4.0. + +@item +Bib@TeX{} in Emacs 19 need @code{tex-insert-quote}, make it autoload +from AUC @TeX{} instead of the standard @code{tex-mode}. + +@item +@code{TeX-auto-generate} failed when repeated. Thanks to Peter Whaite +@samp{<peta@@Thunder.McRCIM.McGill.EDU>} for reporting this. +@end itemize + +@node Version 7.1 +@comment node-name, next, previous, up +@section News in 7.1 + +Coordinator: Per Abrahamsen, 1993. + +@itemize @bullet +@item +Allow multiple @samp{%p} in print commands. + +Suggested by Cliff Krumvieda @samp{<cliff@@cs.cornell.edu>}. + +@item +Improved backward compatibility in @file{auc-tex.el}. Thanks to Ralf +Handl @samp{<handl@@cs.uni-sb.de>}. + +@item +New style hook for @file{german.sty}. + +Disable smart quotes. Press @kbd{C-c C-n} to make it take effect. + +@item +Allow files to have other extensions than ``tex''. + +But no longer allow files to have multiple dots. Sigh. + +@item +Will no longer parse the buffer if it can use the saved state. + +@item +New variable @code{TeX-parse-self}. + +Set it to nil if you never want to parse the buffer when you load it. + +@item +Only offer to save files that belongs to the document. + +When you format the document with @kbd{C-c C-c}, AUC @TeX{} will no +longer offer to save your @file{RMAIL}, @file{.newsrc}, or other files +that does not belong to the document. Suggested by Jim Hetrick +@samp{<hetrick@@phys.uva.nl>}. + +@item +Foil@TeX{} support. + +Thanks to Sven Mattisson @samp{<sven@@tde.lth.se>} + +@item +Smarter about when you need to reformat. + +Thanks to Chris Callsen @samp{<chris@@iesd.auc.dk>}. + +@item +Japanese @TeX{} + +Now supports Japanese @TeX{}. Thanks to Shinji Kobayashi +@samp{<koba@@keisu-s.t.u-tokyo.ac.jp>}. + +@item +Works again under OS/2 and other case insensitive file systems. + +@item +DEMACS support. + +Thanks to Shinji Kobayashi @samp{<koba@@keisu-s.t.u-tokyo.ac.jp>}. + +@item +Better @code{LaTeX-close-environment}. + +Thanks to Piet van Oostrum @samp{<piet@@cs.ruu.nl>}. + +@item +Ispell support. + +Thanks to Piet van Oostrum @samp{<piet@@cs.ruu.nl>}. + +@item +Support for Russian letters. + +Thanks to Justin R. Smith @samp{<jsmith@@king.mcs.drexel.edu>}. + +@item +Sli@TeX{} fixes. + +Many people. + +@item +Fixes for spelling errors. + +Many people. + +@end itemize + +@node Version 7.0 +@comment node-name, next, previous, up +@section Version 7.0 + +Coordinator: Per Abrahamsen, 1993. + +Alpha testers (in order of appearance): Piet van Oostrum +@samp{<piet@@cs.ruu.nl>}, Sven Mattisson @samp{<sven@@tde.lth.se>}, Tim +Geisler @samp{<tmgeisle@@immd8.informatik.uni-erlangen.de>}, Fran E. +Burstall @samp{<F.E.Burstall@@maths.bath.ac.uk>}, Alastair Burt +@samp{<burt@@dfki.uni-kl.de>}, Sridhar Anandakrishnan +@samp{<sak@@essc.psu.edu>}, Kjell Gustafsson +@samp{<kjell@@sccm.Stanford.EDU>}, Uffe Kjaerulff +@samp{<uk@@iesd.auc.dk>}, Kurt Swanson @samp{Kurt.Swanson@@dna.lth.se}, +Mark Utting @samp{<marku@@cs.uq.oz.au>}, Per Norman Oma +@samp{perno@@itk.unit.no}, Naji Mouawad +@samp{<nmouawad@@math.uwaterloo.ca>}, Bo Nygaard Bai +@samp{<bai@@iesd.auc.dk>}, and probably more. + +@itemize @bullet +@item +New keymap. + +The keymap has been changed in order to make it more intuitive to new +users, and because the old bindings did not work well with the new +buffer manipulation commands in tex-buf.el. To use the new bindings, +load @file{tex-init.el} instead of @file{auc-tex.el}. + +The file @file{auc-tex.el} is still available and implements the old +keybindings on top of the new code. + +Print out the reference card (@file{doc/tex-ref.tex}) to see the new +bindings. + +@item +Completely redesigned the buffer handling. + +No part of the interface or the customization variables remain the same, +unless you use the compatibility functions in @file{auc-tex.el}. In +that case the interactive commands remain similar in spirit, but the +customization interface is still changed. + +The file @file{tex-buf.el} has been completely rewritten, and there are +major cleanup in @file{tex-dbg.el}, however the basic functionality +remains the same in this file. The code for both @file{tex-buf.el} and +@file{tex-dbg.el} should be much simpler now and easier to extent. + +@file{auc-tex.el} and @file{tex-site.el} was updated to support the new +interface. I actually believe the moral equivalent to @code{TeX-region} +to work now @t{:-)}, at least I understand the code now. + +The two major functions are now @code{TeX-command-master} and +@code{TeX-command-region}. Each function will prompt you for the +command to execute. AUC @TeX{} will make an educated guess on what +command you want to run, and make that the default. The available +commands are defined in the variable @code{TeX-command-list}. + +@code{TeX-command-master} will run the specified command on the buffers +master file. You can have one command running for each master file. +@code{TeX-command-region} will run the specified command on the current +region, getting the header on trailer from the master file. + +You can have exactly one region command running, independent on how many +master file commands that are running. Commands that operate on the +active process (like @code{TeX-next-error}) will chose the process +associated with buffers master file, unless the last region process is +more recent than all master file processes. + +AUC @TeX{} now insist on knowing the master file for a buffer. If you +do not specify it in the file variable section, and it is not obviously +a master file itself, it will ask you. It will also add the master file +name to the file variables, unless you disable this feature by setting +@code{TeX-add-local} to nil. Furthermore, it will convert @samp{%% +Master:} lines to file variables, unless you disable it by setting +@code{TeX-convert-master} to nil. +@vindex TeX-convert-master + +Functionality removed (for now, it might appear again latter) include +all other functions to start a command (e.g. @code{LaTeX-BibTeX}), and +alternative ways to specify headers and trailers. The only place to get +the header and trailer is from the master file (I can easily change +that, if anyone have such needs). + +@item +Style specific code isolated. + +You can now add style specific information to AUC TeX by writing a +style file somewhere in TeX-style-path. + +The main code is now organized around this principle. + +@item +Automatically generate style files. + +AUC @TeX{} can now automatically extract information from a @TeX{} file, +and will do this when you save a buffer. + +@item +Sli@TeX{} mode. + +Just like @LaTeX{} mode, except that the default command to format run +on the buffer is @samp{slitex}. + +@item +@code{LaTeX-section} completely general. + +Rewrote @file{ltx-sec.el}. + +@itemize @minus +@item +Sectioning level, toc, and title queries can be individually turned off. +@item +Label query can be turned on or off for selected sectioning levels. +@item +Label prefix can be different for different sectioning levels. +@item +If the title (or toc) is empty, point will be positioned there. +@item +Users can add new hooks +@end itemize + +@item +@code{TeX-insert-macro} much smarter. + +It will now prompt for the symbol with completions, and for many symbols +it will also prompt for each argument. There are also completion on +some of the arguments. + +@item +Fixed center in figure environment. + +Thanks to Thomas Koenig @samp{<ig25@@rz.uni-karlsruhe.de>}. + +@item +Changed @code{\M-} to @code{\e} in all keybindings in order to better +support 8-bit input on some GNU Emacs. Thanks to Peter Dalgaard +@samp{<pd@@kubism.ku.dk>}. + +Please, implementors of 8-bit input extensions to GNU Emacs. +@code{\M-x} does @emph{not} means @dfn{@kbd{x} with the 8-bit set}. It +means @dfn{pressing @kbd{x} while holding down the @key{meta} key}. +Some systems (such as X11) are able to tell the different. Thus, even +if you implement 256 byte keymaps, @code{\M-x} should still expand +@code{meta-prefix-char} followed by an @kbd{x} in the keymap. This +allows you to distinguish pressing @kbd{x} while holding down the +@key{meta} key from entering a literal 8-bit character. + +@item +Made the outline commands aware of the document style. + +That is, if the document style is @samp{article}, @samp{\section} will +be one level below the @samp{\documentstyle}, while if the style is +@samp{book}, @samp{\section} will be three levels below +@samp{\documentstyle}. This will make @code{show-children} work better +at the top level. + +@item +The makefiles are closer to GNU coding standard. + +They now understand `prefix' and some other macros. + +@item +Added hooks to be run after list of environments or list of completion +names are updated, and also added a hook to be called after each file +has been loaded. Thanks to Piet van Oostrum @samp{<piet@@cs.ruu.nl>}. + +@item +Added @samp{*} to lot of @code{(interactive)} declarations. + +@item +The outline commands are now always accessible from @LaTeX{} mode. + +@item +Generalized the keyboard remapping and double modes. + +These are found in the file @file{min-key.el}. + +@item +Smart Comments. + +Not really, but there are now two comment functions which use their +arguments to determine what to do, instead of four functions ignoring +their arguments. + +@item +Add outline headers. + +It is now possible to add extra outline headers, by setting the variable +@code{TeX-outline-extra}. + +@item +Smart quotes even smarter. + +If you press @kbd{"} twice, it will insert an real double quote instead +of two (or four) single quotes. This is consistent with how remapping +in @file{min-key.el} is done. + +@item +Automatically untabify buffer when you save it. + +Hands up, everyone who have produced a `last revision' paper containing +an unreadable list of data in the back, because @TeX{} does not +understands tabs. + +@item +Call show-all when you change major mode. + +Thanks to Inge Frick's @samp{<inge@@nada.kth.se>} @file{kill-fix.el} +enhancement, outline minor mode can now guarantee that all text is shown +when you leave the minor mode, even if you leave the minor mode by +changing the major mode. + +@item +Updated documentation for 7.0. + +Also added key, variable, function, and concept indexes, as well as this +history section and a new chapter on multifile documents +(@pxref{Multifile}).@refill + +@end itemize + +@node Version 6.1 +@comment node-name, next, previous, up +@section Version 6.1 + +Coordinator: Per Abrahamsen, 1992. + +@itemize @bullet +@item +@code{TeX-region} might work now (heard that before?). + +Many people reported this one. Especially thanks to Fran Burstall +@samp{<F.E.Burstall@@maths.bath.ac.uk>} and Bill Schworm +@samp{<bill@@schworm.econ.ubc.ca>}.@refill + +@item +The specification format for the @TeX{} command is more general. + +See the documentation for @code{LaTeX-command} and +@code{plain-TeX-command}. + +@item +The specification format for the preview commands is more general. + +See their respective documentation. + +@item +The specification format for the print command is more general. + +See the documentation for @code{TeX-print-command}. + +@item +@code{TeX-args} is marked as obsolete. + +@item +The @samp{"Emergency stop ..."} error. + +Some users of old @TeX{} installations got might might be fixed now. +Thanks to Philip Sterne @samp{<sterne@@dublin.llnl.gov>}. + +@item +It is now possible to change the preview command. + +@dots{} without loading TeX-site first. Thanks to Tim Bradshaw +@samp{<tim.bradshaw@@edinburgh.ac.uk>}. + +@item +New variable TeX-smart-quotes. + +Allow @file{german.sty} users (and others) to disable the mapping of +double quote (@kbd{"} to @samp{``} or @samp{''}). Thanks to Daniel +Hernandez @samp{<danher@@informatik.tu-muenchen.de>}. + +@item +Many minor corrections to the documentation. + +Thanks to Mainhard E. Mayer @samp{<hardy@@golem.ps.uci.edu>}. + +@item +Make test for @code{HOSTTYPE} case insensitive. + +Thanks to Gisli Ottarsson @samp{<gisli@@liapunov.eecs.umisc.edu>}. + +@item +@code{TeX-force-default-mode} + +Set to avoid AUC @TeX{}'s attempts to infer the mode of the file by +itself. + +@end itemize + +@node Version 6.0 +@comment node-name, next, previous, up +@section Version 6.0 + +Coordinator: Kresten Krab Thorup, 1992. + +Preliminary documentation is available in the directory @file{doc}. It +isn't very well written, but I believe it covers most interesting points. +Comments, suggestions, or even rewrites of sections are VERY +WELCOME@dots{} + +LaCheck has been incorporated in the package. The source code for it is +available in the directory @file{lacheck} along with the documentation +for it. Lacheck may also be used from the command line. It is bound to +@kbd{C-c $}. + +Some minor changes in: + +@table @code +@item TeX-region +Should work better with @samp{Master:} option. + +@item LaTeX-environment +Numerous new hooks added by Masayuki Kuwada. + +@item TeX-command-on-region +Removed. @kbd{C-c C-o} used for @code{outline-minor-mode} instead. + +@end table + +And some additional minor fixes... + +@node Ancient History +@comment node-name, next, previous, up +@section Ancient History + +The origin of AUC @TeX{} is @file{tex-mode.el} from Emacs 16. Lars +Peter Fischer @samp{<fischer@@iesd.auc.dk>} wrote the first functions to +insert font macros and Danish characters back in 1986. Per Abrahamsen +@samp{<abraham@@iesd.auc.dk>} wrote the functions to insert environments +and sections, to indent the text, and the outline minor mode in 1987. +Kresten Krab Thorup @samp{<krab@@iesd.auc.dk>} wrote the buffer handling +and debugging functions, the macro completion, and much more, including +much improved indentation and text formatting functions. He also made +the first public release in 1991, and was the main author and +coordinator of every release up to and including 6.0. + +Thanks should also go to all the people who have been a great help +developing the AUC @TeX{} system. Especially all the people on the +@samp{auc-tex} mailing list, who have been very helpful commenting and +pointing out weak points and errors. + +Some of the contributors are listed below. Others are mentioned in the +lisp files or in the History section. + +@table @samp +@item <dduchier@@csi.UOttawa.CA> +Denys Duchier +@item <ferguson@@cs.rochester.edu> +George Ferguson +@item <simons@@ibiza.karlsruhe.gmd.de> +Martin Simons +@item <smith@@pell.anu.edu.au> +Michael Smith +@item <per@@iesd.auc.dk> +Per Hagen +@item <handl@@cs.uni-sb.de> +Ralf Handl +@item <sven@@tde.lth.se> +Sven Mattisson +@item <kuwada@@soliton.ee.uec.ac.jp> +Masayuki Kuwada +@item <tb06@@pl118f.cc.lehigh.edu> +Terrence Brannon +@item <roseman@@hustat.harvard.edu> +Leonard Roseman +@end table + +Special thanks to Leslie Lamport for supplying the source for the LaTeX +error messages in the @file{tex-dbg.el} file. + diff --git a/elpa/auctex-13.1.3/doc/install.texi b/elpa/auctex-13.1.3/doc/install.texi new file mode 100644 index 0000000..19034cb --- /dev/null +++ b/elpa/auctex-13.1.3/doc/install.texi @@ -0,0 +1,628 @@ +@c This is part of the AUCTeX Manual. +@c Copyright (C) 1994, 1996, 2003-2007, 2012-2013, +@c 2015, 2017, 2018, 2020, 2021 Free Software Foundation, Inc. +@c See the file auctex.texi for copying conditions. +@ifset rawfile +@include macros.texi +@node Installation,,(dir),(dir) +@top Installing @AUCTeX{} +@end ifset + +@ifclear rawfile +@node Installation +@chapter Installing @AUCTeX{} +@end ifclear + +The modern and strongly recommended way of installing @AUCTeX{} is by +using the Emacs package manager integrated in Emacs 24 and greater +(@acronym{ELPA}). Simply do @kbd{M-x list-packages @key{RET}}, mark the +auctex package for installation with @kbd{i}, and hit @kbd{x} to execute +the installation procedure. That's all. + +@code{use-package} users can use this simple recipe in their +@code{user-init-file} which essentially does the same as the manual +installation explained above. + +@lisp +(use-package tex + :ensure auctex) +@end lisp + +Using the @acronym{ELPA} version has several advantages. Besides being +platform and @acronym{OS} independent, you will receive intermediate +bugfix releases between major @AUCTeX{} releases conveniently. For past +@acronym{ELPA} releases, see +@url{https://elpa.gnu.org/packages/auctex.html}. +@ifclear rawfile +Once the installation is completed, you can skip the rest of this +section and proceed to @ref{Quick Start}. +@end ifclear + +The remainder of this section is about installing @AUCTeX{} from a +release tarball or from a checkout of the @AUCTeX{} repository. + +Installing @AUCTeX{} should be simple: merely @command{./configure}, +@command{make}, and @code{make install} for a standard site-wide +installation (most other installations can be done by specifying a +@option{--prefix=@dots{}} option). + +On many systems, this will already activate the package, making its +modes the default instead of the built-in modes of Emacs. If this is +not the case, consult @ref{Loading the package}. Please read through +this document fully before installing anything. The installation +procedure has changed as compared to earlier versions. Users of @w{MS +Windows} are asked to consult +@ifset rawfile +the file @file{INSTALL.windows}. +@end ifset +@ifclear rawfile +@xref{Installation under MS Windows}. +@end ifclear + +@ifclear rawfile +@menu +* Prerequisites:: +* Configure:: +* Build/install and uninstall:: +* Loading the package:: +* Advice for package providers:: +* Advice for non-privileged users:: +* Installation under MS Windows:: +* Customizing:: +@end menu +@end ifclear + +@ifset rawfile +@menu +* Prerequisites:: +* Configure:: +* Build/install and uninstall:: +* Loading the package:: +* Advice for package providers:: +* Advice for non-privileged users:: +* Customizing:: +@end menu +@end ifset + +@ifset rawfile +@node Prerequisites +@chapter Prerequisites +@raisesections +@end ifset + +@ifclear rawfile +@node Prerequisites +@section Prerequisites +@end ifclear + +@itemize @bullet +@item GNU Emacs 25.1 or higher + +Using @previewlatex{} requires a version of Emacs compiled with image +support. + +@table @b +@item Windows +Precompiled versions are available from +@uref{https://ftp.gnu.org/gnu/emacs/windows/}. +@item macOS +For an overview of precompiled versions of Emacs for macOS see for +example @uref{https://www.emacswiki.org/emacs/EmacsForMacOS}. +@item GNU/Linux +Most GNU/Linux distributions nowadays provide a recent variant of Emacs +via their package repositories. +@item Self-compiled +Compiling Emacs yourself requires a C compiler and a number of tools and +development libraries. Details are beyond the scope of this manual. +Instructions for checking out the source code can be found at +@uref{https://savannah.gnu.org/git/?group=emacs}. +@end table + +@item A working @TeX{} installation + +Well, @AUCTeX{} would be pointless without that. Processing +documentation requires @TeX{}, @LaTeX{} and Texinfo during installation. +@previewlatex{} requires Dvips or @command{dvipng} for its operation in @acronym{DVI} mode. +The default configuration of @AUCTeX{} is tailored for @w{@TeX{} Live}-based +distributions, but can be adapted easily. + +@item A recent Ghostscript + +This is needed for operation of @previewlatex{} in both @acronym{DVI} +and @acronym{PDF} mode. Ghostscript version 7.07 or newer is required. + +@item GNU make + +Recent @AUCTeX{} uses GNU make specific capabilities in the Makefiles. +If your @acronym{OS}'s default @command{make} command is not GNU make, +you have to obtain it in order to build @AUCTeX{} by yourself. GNU make +is sometimes provided under the name @command{gmake} in your +@acronym{OS}'s binary package system. + +@item The Texinfo package + +Strictly speaking, you can get away without it if you are building +from the distribution tarball, have not modified any files and don't +need a printed version of the manual: the pregenerated info file is +included in the tarball. At least @w{version 4.0} is required. + +@end itemize + +For some known issues with various software, see +@ifset rawfile +the @file{PROBLEMS.preview} file. +@end ifset +@ifclear rawfile +@ref{Known problems,,,preview-latex,the @previewlatex{} manual}. +@end ifclear + +@node Configure +@section Configure + +The first step is to configure the source code, telling it where +various files will be. To do so, run + +@example +./configure @var{options} +@end example + +(Note: if you have fetched @AUCTeX{} from Git rather than +a regular release, you will have to first follow the instructions in +@file{README.GIT}). + +On many machines, you will not need to specify any options, but if +@command{configure} cannot determine something on its own, you'll need to +help it out with one of these options: + +@table @code +@item --prefix=@var{prefix} +All automatic placements for package components will be chosen from +sensible existing hierarchies below this: directories like @file{man}, +@file{share} and @file{bin} are supposed to be directly below +@var{prefix}. + +Only if no workable placement can be found there, in some cases an +alternative search will be made in a prefix deduced from a suitable +binary. + +@file{/usr/local} is the default @var{prefix}, intended to be suitable +for a site-wide installation. If you are packaging this as an +operating system component for distribution, the setting @file{/usr} +will probably be the right choice. See @ref{Advice for package +providers} for detail. + +If you are planning to install the package as a single non-priviledged +user, you will typically set @var{prefix} to your home directory. +Consult @ref{Advice for non-privileged users} for addtional +instructions. + +@item --with-emacs=@var{/path/to/emacs} +If you are using a pretest which isn't in your @env{PATH}, or +@command{configure} is not finding the right Emacs executable, you can +specify it with this option. + +@item --with-lispdir=@var{lispdir} +This option specifies the location of the @file{site-lisp} +directory within @code{load-path} under which the files will get +installed (the bulk will get installed in a subdirectory). +@command{./configure} should figure this out by itself. + +@item --with-auctexstartfile=@file{auctex.el} +@itemx --with-previewstartfile=@file{preview-latex.el} +This is the name of the respective startup files. If @var{lispdir} +contains a subdirectory @file{site-start.d}, the start files are +placed there, and @file{site-start.el} should +load them automatically. Please be aware that you must not move the +start files after installation since other files are found +@emph{relative} to them. + +@item --with-packagelispdir=@file{auctex} +This is the directory where the bulk of the package gets located. The +startfile adds this into @code{load-path}. + +@item --with-auto-dir=@var{/dir} +You can use this option to specify the directory containing +automatically generated information by @kbd{M-x TeX-auto-generate-global @key{RET}}. It is not necessary for most +@TeX{} installs, but may be used if you don't like the directory that +configure is suggesting. + +@item --help +This is not an option specific to @AUCTeX{}. A number of standard +options to @command{configure} exist, and we do not have the room to +describe them here; a short description of each is available, using +@option{--help}. + +@c FIXME: It seems this no longer holds. +@c If you use @samp{--help=recursive}, then also @previewlatex{}-specific +@c options will get listed. + +@item --disable-preview +This disables configuration and installation of @previewlatex{}. This +option is not actually recommended. If your Emacs does not support +images, you should really upgrade to a newer version. Distributors +should, if possible, refrain from distributing @AUCTeX{} and +@previewlatex{} separately in order to avoid confusion and upgrade +hassles if users install partial packages on their own. + +@item --with-texmf-dir=@var{/dir} +@itemx --without-texmf-dir +@cindex preview-install-styles +This option is used for specifying a @acronym{TDS}-compliant directory +hierarchy. Using @code{--with-texmf-dir=@var{/dir}} you can specify +where the @TeX{} @acronym{TDS} directory hierarchy resides, and the +@TeX{} files will get installed in +@file{@var{/dir}/tex/latex/preview/}. + +If you use the @option{--without-texmf-dir} option, the @TeX{}-related +files will be kept in the Emacs Lisp tree, and at runtime the +@env{TEXINPUTS} environment variable will be made to point there. You +can install those files into your own @TeX{} tree at some later time +with @kbd{M-x preview-install-styles @key{RET}}. + +@item --with-tex-dir=@var{/dir} +If you want to specify an exact directory for the preview @TeX{} files, +use @code{--with-tex-dir=@var{/dir}}. In this case, the files will be +placed in @file{@var{/dir}}, and you'll also need the following option: + +@item --with-doc-dir=@var{/dir} +This option may be used to specify where the @TeX{} documentation goes. +It is to be used when you are using @code{--with-tex-dir=@var{/dir}}, +but is normally not necessary otherwise. +@end table + +@node Build/install and uninstall +@section Build/install and uninstall + +@cindex Installation +@cindex Make +@cindex Uninstallation + +Once @command{configure} has been run, simply enter + +@example +make +@end example + +@noindent +at the prompt to byte-compile the lisp files, extract the @TeX{} files +and build the documentation files. To install the files into the +locations chosen earlier, type + +@example +make install +@end example + +@noindent +You may need special privileges to install, e.g., if you are installing +into system directories. + +Should you want to completely remove the installed package, in the same +directory you built @AUCTeX{} run + +@example +make uninstall +@end example + +@noindent +You will need administration privileges if you installed the package +into system directories. + +@node Loading the package +@section Loading the package +@cindex @file{init.el} +@cindex @file{.emacs} + +You can detect the successful activation of @AUCTeX{} and +@previewlatex{} in the menus after loading a @LaTeX{} file like +@file{circ.tex}: @AUCTeX{} then gives you a @samp{Command} menu, +and @previewlatex{} gives you a @samp{Preview} menu. + +@cindex @file{auctex.el} +@cindex @file{tex-site.el} +With Emacs (or if you explicitly disabled use of the package system), +the startup files @file{auctex.el} and @file{preview-latex.el} may +already be in a directory of the @file{site-start.d/} variety if your +Emacs installation provides it. In that case they should be +automatically loaded on startup and nothing else needs to be done. If +not, they should at least have been placed somewhere in your +@code{load-path}. You can then load them by placing the lines + +@lisp +(load "auctex.el" nil t t) +(load "preview-latex.el" nil t t) +@end lisp +@noindent +into your init file such as @file{init.el} or @file{.emacs}. + +If you explicitly used @code{--with-lispdir}, you may need to add the +specified directory into Emacs' @code{load-path} variable by adding +something like + +@lisp +(add-to-list 'load-path "~/elisp") +@end lisp +@noindent +before the above lines into your Emacs startup file. + +For site-wide activation in GNU Emacs, see +@ifset rawfile +below. +@end ifset +@ifclear rawfile +@xref{Advice for package providers}. +@end ifclear + +Once activated, the modes provided by @AUCTeX{} are used per default for +all supported file types. If you want to change the modes for which it +is operative instead of the default, use +@example +@kbd{M-x customize-option @key{RET} TeX-modes @key{RET}} +@end example + +If you want to remove a preinstalled @AUCTeX{} completely before any of +its modes have been used, +@lisp +(unload-feature 'tex-site) +@end lisp +@noindent +should accomplish that. + +@node Advice for package providers +@section Providing @AUCTeX{} as a package + +As a package provider, you should make sure that your users will be +served best according to their intentions, and keep in mind that a +system might be used by more than one user, with different +preferences. + +There are people that prefer the built-in Emacs modes for editing +@TeX{} files, in particular plain @TeX{} users. There are various +ways to tell @AUCTeX{} even after auto-activation that it should +not get used, and they are described in +@ifset rawfile +the @file{README} file. +@end ifset +@ifclear rawfile +@ref{Introduction,,Introduction to @AUCTeX{}}. +@end ifclear + +So if you have users that don't want to use the preinstalled @AUCTeX{}, +they can easily get rid of it. Activating @AUCTeX{} by default is +therefore a good choice. + +If the installation procedure did not achieve this already by placing +@file{auctex.el} and @file{preview-latex.el} into a possibly existing +@file{site-start.d} directory, you can do this by placing + +@lisp +(load "auctex.el" nil t t) +(load "preview-latex.el" nil t t) +@end lisp + +@noindent in the system-wide @file{site-start.el}. + +The @option{--without-texmf-dir} option can be convenient for systems that +are intended to support more than a single TeX distribution. Since more +often than not @TeX{} packages for operating system distributions are +either much more outdated or much less complete than separately provided +systems like @w{@TeX{} Live}, this method may be generally preferable +when providing packages. + +The following package structure would be adequate for a typical fully +supported Unix-like installation: + +@c FIXME: teTeX is much outdated now. +@table @samp +@item preview-tetex +Style files and documentation for @file{preview.sty}, placed into a +@TeX{} tree where it is accessible from the te@TeX{} executables usually +delivered with a system. If there are other commonly used @TeX{} system +packages, it might be appropriate to provide separate packages for +those. +@item auctex-emacs-tetex +This package will require the installation of @samp{preview-tetex} and +will record in @code{TeX-macro-global} where to find the @TeX{} tree. +It is also a good idea to run +@example +emacs -batch -f TeX-auto-generate-global +@end example +when either @AUCTeX{} or te@TeX{} get installed or upgraded. If your +users might want to work with a different @TeX{} distribution (nowadays +pretty common), instead consider the following: +@item auctex-emacs +This package will be compiled with @option{--without-texmf-dir} and will +consequently contain the @samp{preview} style files in its private +directory. It will probably not be possible to initialize +@code{TeX-macro-global} to a sensible value, so running +@code{TeX-auto-generate-global} does not appear useful. This package +would neither conflict with nor provide @samp{preview-tetex}. +@end table + +@node Advice for non-privileged users +@section Installation for non-privileged users + +Often people without system administration privileges want to install +software for their private use. In that case you need to pass more +options to the @command{configure} script. + +The main expedient is using the @option{--prefix} option to the +@command{configure} script, and let it point to the personal home +directory. In that way, resulting binaries will be installed under the +@file{bin} subdirectory of your home directory, manual pages under +@file{man} and so on. It is reasonably easy to maintain a bunch of +personal software, since the prefix argument is supported by most +@command{configure} scripts. + +You often need to specify @option{--with-lispdir} option as well. +If you haven't installed Emacs under your home directory and use Emacs +installed in system directories, the @command{configure} script might not +be able to figure out suitable place to install lisp files under your +home directory. In that case, the @command{configure} script would +silently choose, by default, the @file{site-lisp} directory within +@code{load-path} for the place, where administration privileges are +usually required to put relevant files. Thus you will have to tell +the @command{configure} script explicitly where to put those files by, +e.g., @code{--with-lispdir=@samp{/home/myself/share/emacs/site-lisp}}. + +You'll have to add something like +@samp{/home/myself/share/emacs/site-lisp} to your @code{load-path} +variable, if it isn't there already. + +In addition, you will have to tell @command{configure} script where to +install @TeX{}-related files such as @file{preview.sty} if +@previewlatex{} isn't disabled. It is enough to specify +@option{--with-texmf-dir=@file{$HOME/texmf}} for most typical cases, but +you have to create the direcotry @file{$HOME/texmf} in advance if it +doesn't exist. If this prescription doesn't work, consider using one or +more of the options @code{--with-texmf-dir=@var{/dir}}, +@code{--without-texmf-dir}, @code{--with-tex-dir=@var{/dir}} and +@code{--with-doc-dir=@var{/dir}}. See @ref{Configure} for detail of +these options. + +Now here is another thing to ponder: perhaps you want to make it easy +for other users to share parts of your personal Emacs configuration. In +general, you can do this by writing @samp{~myself/} anywhere where you +specify paths to something installed in your personal subdirectories, +not merely @samp{~/}, since the latter, when used by other users, will +point to non-existent files. + +For yourself, it will do to manipulate environment variables in your +@file{.profile} resp.@: @file{.login} files. But if people will be +copying just Elisp files, their copies will not work. While it would +in general be preferable if the added components where available from +a shell level, too (like when you call the standalone info reader, or +try using @file{preview.sty} for functionality besides of Emacs +previews), it will be a big help already if things work from inside +of Emacs. + +Here is how to do the various parts: + +@subheading Making the Elisp available + +In GNU Emacs, it should be sufficient if people just do + +@lisp +(load "~myself/share/emacs/site-lisp/auctex.el" nil t t) +(load "~myself/share/emacs/site-lisp/preview-latex.el" nil t t) +@end lisp +@noindent +where the path points to your personal installation. The rest of the +package should be found relative from there without further ado. + +@subheading Making the Info files available + +For making the info files accessible from within Elisp, something like +the following might be convenient to add into your or other people's +startup files: + +@lisp +(eval-after-load 'info + '(add-to-list 'Info-directory-list "~myself/info")) +@end lisp + +@subheading Making the @LaTeX{} style available + +If you want others to be able to share your installation, you should +configure it using @option{--without-texmf-dir}, in which case things +should work as well for them as for you. + +@subsection Using @AUCTeX{} from local Git repo + +With the techniques described above, it is also possible to use @AUCTeX{} +directly from a local Git repository. Let's assume you have your Git +repositories under @samp{~/development/}. + +First, you have to fetch a copy of the @AUCTeX{} Git repository. In a +shell, change directory to @samp{~/development/} and do: +@example +git clone https://git.savannah.gnu.org/git/auctex.git +@end example + +Now change directory to @samp{~/development/auctex} and run +@samp{./autogen.sh}. Next thing is to run @command{configure} like this: +@example +./configure --without-texmf-dir --with-lispdir=. +@end example + +@noindent +When finished, simply enter +@example +make +@end example +@noindent +and you're finished. Note that the @samp{make install} step is not +necessary. + +Now you have to tell Emacs about the plan. The following variables must +be set in your init file because their normal values are only correct when +@AUCTeX{} is installed: +@lisp +(setq TeX-data-directory "~/development/auctex" + TeX-lisp-directory TeX-data-directory) +@end lisp + +@noindent +The info files will be available with this: +@lisp +(eval-after-load 'info + '(add-to-list 'Info-additional-directory-list + "~/development/auctex/doc")) +@end lisp + +@noindent +Now you're ready to load @file{auctex.el} and @file{preview-latex.el} out +of this directory: +@lisp +(load "~/development/auctex/auctex.el" nil t t) +(load "~/development/auctex/preview-latex.el" nil t t) +@end lisp + +@ifclear rawfile +@node Installation under MS Windows +@section Installation under MS Windows +@include wininstall.texi +@end ifclear + +@node Customizing +@section Customizing +@cindex Site initialization +@cindex Initialization +@cindex @file{tex-site.el} +@cindex Personal customization +@cindex Site customization +@cindex Customization +@cindex Customization, personal +@cindex Customization, site +Most of the site-specific customization should already have happened +during configuration of @AUCTeX{}. Any further customization can be +done with customization buffers directly in Emacs. Just type @kbd{M-x +customize-group @key{RET} AUCTeX @key{RET}} to open the customization group for +@AUCTeX{} or use the menu entries provided in the mode menus. Editing +the file @file{tex-site.el} as suggested in former versions of @AUCTeX{} +should not be done anymore because the installation routine will +overwrite those changes. + +You might check some options with a special significance. They are +accessible directly by typing @kbd{M-x customize-option @key{RET} <option> +@key{RET}}. + +@defopt TeX-macro-global +Directories containing the site's @TeX{} style files. +@end defopt + +Normally, @AUCTeX{} will only allow you to complete macros and +environments which are built-in, specified in @AUCTeX{} style files or +defined by yourself. If you issue the @kbd{M-x +TeX-auto-generate-global} command after loading @AUCTeX{}, you will be +able to complete on all macros available in the standard style files +used by your document. To do this, you must set this variable to a list +of directories where the standard style files are located. The +directories will be searched recursively, so there is no reason to list +subdirectories explicitly. Automatic configuration will already have +set the variable for you if it could use the program @command{kpsewhich}. +In this case you normally don't have to alter anything. + +@c Local Variables: +@c mode: texinfo +@c TeX-master: "auctex" +@c End: diff --git a/elpa/auctex-13.1.3/doc/intro.texi b/elpa/auctex-13.1.3/doc/intro.texi new file mode 100644 index 0000000..0bbf739 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/intro.texi @@ -0,0 +1,106 @@ +@include macros.texi +@ifset rawfile +@paragraphindent none +This is the README file for the AUCTeX distribution. + +@quotation +Copyright (C) 2008, 2017, 2018 Free Software Foundation, Inc. + +Copying and distribution of this file, with or without modification, are +permitted in any medium without royalty provided the copyright notice +and this notice are preserved. +@end quotation + +@chapheading Introduction to @AUCTeX{} +@end ifset + +@ifclear rawfile +@node Summary +@chapter Overview of @AUCTeX{} +@end ifclear + +@ifset rawfile +This file gives a brief overview of what @AUCTeX{} is. It is +@strong{not} an attempt to document @AUCTeX{}. Real documentation for +@AUCTeX{} is available in the manual, which should be available as an +info file after installation. +@end ifset + +@AUCTeX{} is a comprehensive customizable integrated environment for +writing input files for @TeX{}, @LaTeX{}, @ConTeXt{}, Texinfo, and +doc@TeX{} using Emacs. + +It supports you in the insertion of macros, environments, and sectioning +commands by providing completion alternatives and prompting for +parameters. It automatically indents your text as you type it and lets +you format a whole file at once. The outlining and folding facilities +provide you with a focused and clean view of your text. + +@AUCTeX{} lets you process your source files by running @TeX{} and +related tools (such as output filters, post processors for generating +indices and bibliographies, and viewers) from inside Emacs. @AUCTeX{} +lets you browse through the errors @TeX{} reported, while it moves the +cursor directly to the reported error, and displays some documentation +for that particular error. This will even work when the document is +spread over several files. + +One component of @AUCTeX{} that @LaTeX{} users will find attractive is +@previewlatex{}, a combination of folding and in-source previewing +that provides true ``What You See Is What You Get'' experience in your +sourcebuffer, while letting you retain full control. +@ifset rawfile +For more information, see further below. +@end ifset + +More detailed information about the features and usage of @AUCTeX{} can +be found in the +@ifset rawfile +@AUCTeX{} manual. You can access it from within Emacs by typing +@kbd{C-h i d m auctex @key{RET}}. If you prefer the standalone info +reader, issue the command @code{info auctex} in a terminal. +@end ifset +@ifclear rawfile +remainder of this manual. +@end ifclear + +@AUCTeX{} is written entirely in Emacs Lisp, and hence you can easily +add new features for your own needs. It is a GNU project and +distributed under the `GNU General Public License Version 3'. + +The most recent version is always available at +@url{https://ftp.gnu.org/pub/gnu/auctex/}. + +WWW users may want to check out the @AUCTeX{} page at +@url{https://www.gnu.org/software/auctex/}. + +For comprehensive information about how to install @AUCTeX{} +@ifset rawfile +read the file @file{INSTALL} or @file{INSTALL.windows}, respectively. +@end ifset +@ifclear rawfile +@xref{Installation}, or @ref{Installation under MS Windows}, +respectively. +@end ifclear + +If you are considering upgrading @AUCTeX{}, the recent changes are +described in +@ifset rawfile +the @file{CHANGES} file. +@end ifset +@ifclear rawfile +@ref{Changes}. +@end ifclear + +If you want to discuss @AUCTeX{} with other users or its developers, +there are several mailing lists you can use. + +Send a mail with the subject ``subscribe'' to +@email{auctex-request@@gnu.org} in order to join the general discussion +list for @AUCTeX{}. Articles should be sent to @email{auctex@@gnu.org}. +In a similar way, you can subscribe to the @email{info-auctex@@gnu.org} +list for just getting important announcements about @AUCTeX{}. The list +@email{bug-auctex@@gnu.org} is for bug reports which you should usually +file with the @kbd{M-x TeX-submit-bug-report @key{RET}} command. If you +want to address the developers of @AUCTeX{} themselves with technical +issues, they can be found on the discussion list +@email{auctex-devel@@gnu.org}. diff --git a/elpa/auctex-13.1.3/doc/macros.texi b/elpa/auctex-13.1.3/doc/macros.texi new file mode 100644 index 0000000..4162d05 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/macros.texi @@ -0,0 +1,89 @@ +@ifclear macros +@set macros +@ifnottex +@macro AUCTeX {} +AUC@TeX{} +@end macro +@macro ConTeXt {} +Con@TeX{}t +@end macro +@macro previewlatex {} +preview-latex +@end macro +@macro fontlatex {} +font-latex +@end macro +@ifset no-acronym +@clear no-acronym +@macro acronym {text} +@sc{\text\} +@end macro +@end ifset +@ifset no-env +@clear no-env +@macro env {text} +@code{\text\} +@end macro +@end ifset +@ifset no-option +@clear no-option +@macro option {text} +@samp{\text\} +@end macro +@end ifset +@ifset no-command +@clear no-command +@macro command {text} +@samp{\text\} +@end macro +@end ifset +@end ifnottex +@ifset no-sansserif +@macro sansserif {text}@c +@iftex +{@textsf \text\}@c +@end iftex +@ifnottex +\text\@c +@end ifnottex +@end macro +@end ifset +@tex +\global\let\savedTeX\TeX +\gdef\TeX#1{\savedTeX#1} +\gdef\LaTeX{% + L\kern-.36em\raise.3ex\hbox{\sc{a}}\kern-.15em\TeX} +\gdef\previewlatex#1{% + {\sf preview-latex}#1} +\gdef\fontlatex#1{% + {\sf font-latex}#1} +\gdef\AUCTeX{AUC\TeX} +\gdef\ConTeXt#1{% + Con\TeX t#1} +\toks0\expandafter{\indexnofonts + \def\TeX#1{TeX#1}% + \def\LaTeX#1{LaTeX#1}\def\previewlatex#1{preview-latex#1}} +\xdef\indexnofonts{\the\toks0} +\ifx\commondummies\undefined \else + \toks0\expandafter{\commondummies + \def\TeX#1{TeX#1}% + \def\LaTeX#1{LaTeX#1}\def\previewlatex#1{preview-latex#1}} + \xdef\commondummies{\the\toks0} +\fi +\ifx\definedummies\undefined \else + \toks0\expandafter{\definedummies + \def\TeX#1{TeX#1}% + \def\LaTeX#1{LaTeX#1}\def\previewlatex#1{preview-latex#1}} + \xdef\definedummies{\the\toks0} +\fi +\ifx\acronym\undefined \gdef\acronym#1{{\smallcaps \lowercase{#1}}} \fi +\ifx\env\undefined \global\let\env=\code \fi +\ifx\option\undefined \global\let\option=\samp \fi +\ifx\command\undefined \global\let\command=\samp \fi +%Bug fix for texinfo.tex: +\gdef\cslet#1#2{% +\expandafter\let +\csname#1\expandafter\endcsname +\csname#2\endcsname} +@end tex +@end ifclear diff --git a/elpa/auctex-13.1.3/doc/preview-dtxdoc.pl b/elpa/auctex-13.1.3/doc/preview-dtxdoc.pl new file mode 100755 index 0000000..8eaa33d --- /dev/null +++ b/elpa/auctex-13.1.3/doc/preview-dtxdoc.pl @@ -0,0 +1,156 @@ +#!/usr/bin/perl +# -*- coding: iso-latin-1; -*- + +# Autoconverter from preview.dtx to preview-dtxdoc.texi + +# Author: Jan-Åke Larsson <jalar@mai.liu.se> +# Maintainer: auctex-devel@gnu.org + +# Copyright (C) 2002, 2005, 2020, 2021 Free Software Foundation, Inc. + +# This file is part of AUCTeX. + +# AUCTeX is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. + +# AUCTeX is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with AUCTeX; see the file COPYING. If not, write to the Free +# Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, +# MA 02110-1301, USA. + +# Commentary: + +# Simpleminded autoconverter from preview.dtx to preview-dtxdoc.texi +# run as 'perl preview-dtxdoc.pl ../latex/preview.dtx preview-dtxdoc.texi' + +die "Usage: perl preview-dtxdoc.pl infile outfile" unless ($#ARGV == 1); +open(STDIN, $ARGV[0]) || die "Can't open $ARGV[0] for reading"; +open(STDOUT, "> $ARGV[1]") || die "Can't open $ARGV[1] for writing"; + + +# Eat header +MUNGE: while (<STDIN>) { + last MUNGE if /^% *.section/; +} + +# Fish out possible CR characters. +/(\r*)$/; +$cr = $1; + + +# Noindent is used sometimes after \end{quote} (see below) +$noindent=""; +# Quote environments is translated into @example _without_ +# @code{..} inside (see below) +$quote=""; +MAIN: while (<STDIN>) { + s/^%//; + s/\\%/%/g; + + # Comment + s/\^\^A.*\n//; + + # Text-substitution macros + s/\@/\@\@/g; + s/\\#/#/g; + s/AUC~?\\TeX[\\ ]?/\@AUCTeX{}/g; + s/\\LaTeX[\\ ]?/\@LaTeX{}/g; + s/\\TeX[\\ ]?/\@TeX{}/g; + s/\\previewlatex[\\ ]?/\@previewlatex{}/g; + s/EPS/\@acronym{EPS}/g; + s/DVI/\@acronym{DVI}/g; + s/~/\@w{ }/g; + s/^ *//; + # Environments + if (s/\\begin\{quote\}/$cr\n\@example/) { + $quote="yes" } + if (/^\w/) { + print $noindent } + $noindent = ""; + if (s/\\end\{quote\}/\@end example$cr\n/) { + $quote=""; + $noindent="\@noindent$cr\n" } + s/\\begin\{description\}/$cr\n\@table \@w/; + # Convoluted pattern: handle + # \item[|...|], \item[\meta{..}] and \item[{|[]|}] + s/\\item\[\{?(.+?[\|\}])\}?\] ?/\@item $1$cr\n/; + s/\\end\{description\}/\@end table$cr\n/; + s/\\begin\{enumerate\}/$cr\n\@enumerate/; + s/\\item /\@item /; + s/\\end\{enumerate\}/\@end enumerate$cr\n/; + + # Formatting (\cmd is special within {quote}) + s/\\texttt/\@option/g; + s/\\marg\{([^}]+)\}/\@{\@var{$1}\@}/g; + s/\\meta/\@var/g; + s/\\emph/\@emph/g; + s/\\cmd(\\[\(\)\w]+)/|$1|/g; + s/\\cmd\{(.*?)\}/|$1|/g; + s/\\oarg\{([^}]+?)\}/\[\@var{$1}\]/g; + s/\\char.//g; + s/\\raggedright$cr\n//g; + s/\\DescribeEnv\{(.*?)\} /\@item \\begin\@{$1\@}\@dots{}\\end\@{$1\@}$cr\n/; + if (s/\\DescribeMacro\{(.*?)\}( |$cr\n)/\@item $1$cr\n/) { + # Index entries for two important macros + if (/(\\Preview(Macro|Environment))( |$cr\n)/) { + $_ .= "\@findex $1$cr\n"; + } + } + + # ||||||| Hell... I hate bars + # Braces WITHIN bars should be escaped like so: @{ @} + # and |..| translates to @code{..} or @file{..} depending on content + # and to .. if in {quote} + @chunks = split /\|/; + $odd=0; + COMMAND: foreach (@chunks) { + if ($odd==0) { + $odd=1; + } else { + s/\{/\@\{/g; + s/\}/\@\}/g; + if (! $quote) { + if (/[.\/]/) { + $_="\@file\{".$_."\}"; + } else { + $_="\@code\{".$_."\}"; + } + } + $odd=0; + } + } + $_=join("",@chunks); + # Argh! mixed types occurs in @code{...}@var{..}@file{..} + # Should be @file{...@var{..}..} + s/\@code(\S*?)\}(\S*)\@file\{/\@file$1$2/g; + + # Texinfo @node-ification + if (s/\\section\{(.*)\}/\@subsection $1/) { + if (s/[Oo]ptions/options/) { + $_="\@menu$cr\n" . +"* Package options::$cr\n" . +"* Provided commands::$cr\n" . +"\@end menu$cr\n$cr\n" . +"\@node Package options, Provided commands, The LaTeX style file, The LaTeX style file$cr\n" . $_; + } elsif (s/[Cc]ommands/commands/) { + # \Describe... needs @table + $_= "\@node Provided commands, ,Package options, The LaTeX style file$cr\n" . + $_ . "$cr\n\@table \@code$cr\n"; + } + } + + # Stop here + # \Describe.... needs @end table + if (/^.StopEventually/) { + print "\@end table$cr\n"; + last MAIN; + } + print $_; +} diff --git a/elpa/auctex-13.1.3/doc/preview-faq.texi b/elpa/auctex-13.1.3/doc/preview-faq.texi new file mode 100644 index 0000000..bf16c7f --- /dev/null +++ b/elpa/auctex-13.1.3/doc/preview-faq.texi @@ -0,0 +1,306 @@ +@c This is part of the preview-latex manual. +@c Copyright (C) 2002, 2003, 2004, 2005, 2006, 2009 +@c 2017, 2021 Free Software Foundation, Inc. +@c See file preview-latex.texi for copying conditions. +@ifset rawfile +@include macros.texi + +@node Frequently Asked Questions, Introduction to FAQ, (dir), (dir) +@top Frequently Asked Questions about @previewlatex{} + +@contents + +@end ifset + +@menu +* Introduction to FAQ:: +* Requirements:: +* Installation Trouble:: +* Customization:: +* Troubleshooting:: +* Other formats:: +@end menu + +@comment we need at least one chapter, or the numbers disappear in the +@comment plain version of the FAQ. + +@ifset rawfile +@node Introduction to FAQ, Requirements, Frequently Asked Questions, Frequently Asked Questions +@chapter Introduction +@raisesections +@end ifset +@ifclear rawfile +@node Introduction to FAQ, Requirements, Frequently Asked Questions, Frequently Asked Questions +@section Introduction +@end ifclear + +@subsection How can I contribute to the FAQ? + +Send an email with the subject: +@example +Preview FAQ +@end example +to @email{auctex-devel@@gnu.org}. + +@node Requirements, Installation Trouble, Introduction to FAQ, Frequently Asked Questions +@section Requirements + +@subsection Which version of Emacs is needed? + +@previewlatex{} nominally requires @w{GNU Emacs} with a version of at +least 25.1. + +@subsection Which versions of Ghostscript and @AUCTeX{} are needed? + +We recommend to use GNU or AFPL Ghostscript with a version of at least +7.07. + +@previewlatex{} has been distributed as part of @AUCTeX{} since version +11.80. If your version of @AUCTeX{} is older than that, or if it does +not contain a working copy of @previewlatex{}, complain to wherever you +got it from. + +@subsection I have trouble with the display format... +We recommend keeping the variable @code{preview-image-type} set to +@code{dvipng} (if you have it installed) or @code{png}. This is the +default and can be set via the @samp{Preview/Customize} menu. + +All other formats are known to have inconveniences, either in file size +or quality. There are some Emacs versions around not supporting +@acronym{PNG}; the proper way to deal with that is to complain to your +Emacs provider. Short of that, checking out @acronym{PNM} or +@acronym{JPEG} formats might be a good way to find out whether the lack +of @acronym{PNG} format support might be the only problem with your +Emacs. + +@subsection For which OS does preview work? + +It is known to work under the X Window System for Linux and for several +flavors of Unix: we have reports for HP and Solaris. + +There are several development versions of Emacs around for native MacOS +Carbon, and @previewlatex{} is working with them, too. + +With Windows, both native Emacs and Cygwin Emacs should work. However, it +is known that @url{https://miktex.org/,MiK@TeX{}} sometimes doesn't work +with @previewlatex{}. In that case, use +@url{https://tug.org/texlive/,@TeX{} Live} instead. + +@node Installation Trouble, Customization, Requirements, Frequently Asked Questions +@section Installation Trouble + +@subsection I just get @samp{LaTeX found no preview images}. + +The reason for this is that @LaTeX{} found no preview images in the +document in question. + +One reason might be that there are no previews to be seen. If you have +not used @previewlatex{} before, you might not know its manner of +operation. One sure-fire way to test if you just have a document where +no previews are to be found is to use the provided example document +@file{circ.tex} (you will have to copy it to some directory where you +have write permissions). If the symptom persists, you have a problem, +and the problem is most likely a @LaTeX{} problem. Here are possible +reasons: + +@table @asis + +@item Filename database not updated +Various @TeX{} distributions have their own ways of knowing where the +files are without actually searching directories. The normal +@previewlatex{} installation should detect common tools for that purpose +and use them. If this goes wrong, or if the files get installed into a +place where they are not looked for, the @LaTeX{} run will fail. + +@item An incomplete manual installation +This should not happen if you followed installation instructions. +Unfortunately, people know better all the time. If only +@file{preview.sty} gets installed without a set of supplementary files +also in the @file{latex} subdirectory, @previewlatex{} runs will not +generate any errors, but they will not produce any previews, either. + +@item An outdated @file{preview} installation +The @file{preview.sty} package is useful for more than just +@previewlatex{}. For example, it is part of @w{@TeX{} Live}. So you have +to make sure that @previewlatex{} does not get to work with outdated +style and configuration files: some newer features will not work with +older @TeX{} style files, and really old files will make +@previewlatex{} fail completely. There usual is a local @file{texmf} +tree, or even a user-specific tree that are searched before the default +tree. Make sure that the first version of those files that gets found +is the correct one. +@end table + +@node Customization, Troubleshooting, Installation Trouble, Frequently Asked Questions +@section Customization + +@subsection How to include additional environments like @code{enumerate} + +By default, @previewlatex{} is intended mainly for displaying +mathematical formulas, so environments like @code{enumerate} or +@code{tabular} (except where contained in a float) are not included. +You can include them however manually by adding the lines: + +@example +\usepackage[displaymath,textmath,sections,graphics,floats]@{preview@} +\PreviewEnvironment@{enumerate@} +@end example +@noindent +in your document header, that is before + +@example +\begin@{document@} +@end example +@noindent +In general, @file{preview} should be loaded as the last thing before +the start of document. + +Be aware that + +@example +\PreviewEnvironment@{...@} +@end example +@noindent +does not accept a comma separated +list! Also note that by putting more and more + +@example +\PreviewEnvironment@{...@} +@end example +@noindent +in your document, it will look more and more like a @acronym{DVI} file +preview when running @previewlatex{}. Since each preview is treated as +one large monolithic block by Emacs, one should really restrict +previews to those elements where the improvement in visual +representation more than makes up for the decreased editability. + +@subsection What if I don't want to change the document? +The easiest way is to generate a configuration file in the current +directory. You can basically either create @file{prdefault.cfg} which +is used for any use of the @samp{preview} package, or you can use +@file{prauctex.cfg} which only applies to the use from with Emacs. Let +us assume you use the latter. In that case you should write something like + +@example +\InputIfFileExists@{preview/prauctex.cfg@}@{@}@{@} +\PreviewEnvironment@{enumerate@} +@end example +@noindent +in it. The first line inputs the system-wide default configuration +(the file name should match that, but not your own +@file{prauctex.cfg}), then you add your own stuff. + +@subsection Suddenly I get gazillions of ridiculous pages?!? + +When @previewlatex{} works on extracting its stuff, it typesets each +single preview on a page of its own. This only happens when actual +previews get generated. Now if you want to configure @previewlatex{} in +your document, you need to add your own @code{\usepackage} call to +@samp{preview} so that it will be able to interpret its various +definition commands. It is an error to add the @code{active} option to +this invocation: you don't want the package to be active unless +@previewlatex{} itself enables the previewing operation (which it will). + +@subsection Does @previewlatex{} work with presentation classes? + +@previewlatex{} should work with most presentation classes. However, +since those classes often have macros or pseudo environments +encompassing a complete slide, you will need to use the customization +facilities of @file{preview.sty} to tell it how to resolve this, whether +you want no previews, previews of whole slides or previews of inner +material. + +@node Troubleshooting, Other formats, Customization, Frequently Asked Questions +@section Troubleshooting + +@subsection Preview causes all sort of strange error messages + +When running @previewlatex{} and taking a look at either log file or +terminal output, lots of messages like + +@example +! Preview: Snippet 3 started. +<-><-> + +l.52 \item Sie lassen sich als Funktion $ + y = f(x)$ darstellen. +! Preview: Snippet 3 ended.(491520+163840x2494310). +<-><-> + +l.52 \item Sie lassen sich als Funktion $y = f(x)$ + darstellen. +@end example +@noindent +appear (previous versions generated messages looking even more like +errors). Those are not real errors (as will be noted in the log +file). Or rather, while they @strong{are} really @TeX{} error +messages, they are intentional. This currently is the only reliable +way to pass the information from the @LaTeX{} run of @previewlatex{} to +its Emacs part about where the previews originated in the source text. +Since they are actual errors, you will also get @AUCTeX{} to state +@example +Preview-LaTeX exited as expected with code 1 at Wed Sep 4 17:03:30 +@end example +@noindent +after the @LaTeX{} run in the run buffer. This merely indicates that +errors were present, and errors will always be present when +@previewlatex{} is operating. There might be also real errors, so in +case of doubt, look for them explicitly in either run buffer or the +resulting @file{.log} file. + +@subsection Why do my @acronym{DVI} and @acronym{PDF} output files vanish? + +In order to produce the preview images @previewlatex{} runs @LaTeX{} on +the master or region file. The resulting @acronym{DVI} or @acronym{PDF} +file can happen to have the same name as the output file of a regular +@LaTeX{} run. So the regular output file gets overwritten and is +subsequently deleted by @previewlatex{}. + +@subsection My output file suddenly only contains preview images?! + +As mentioned in the previews @acronym{FAQ} entry, @previewlatex{} might +use the file name of the original output file for the creation of +preview images. If the original output file is being displayed with a +viewer when this happens, you might see strange effects depending on the +viewer, e.g.@: a message about the file being corrupted or the display of +all the preview images instead of your typeset document. (Also +@pxref{Customization}.) + + +@node Other formats, , Troubleshooting, Frequently Asked Questions +@section @previewlatex{} when not using @LaTeX{} + +@subsection Does @previewlatex{} work with PDF@LaTeX{}? + +Yes, as long as you use @AUCTeX{}'s own PDF@LaTeX{} mode and have not +messed with @samp{TeX-command-list}. + +@subsection Does @previewlatex{} work with @samp{elatex}? + +No problem here. If you configure your @AUCTeX{} to use @samp{elatex}, +or simply have @samp{latex} point to @samp{elatex}, this will work fine. +Modern @TeX{} distributions use e@TeX{} for @LaTeX{}, anyway. + +@subsection Does @previewlatex{} work with @ConTeXt{}? + +In short, no. The @samp{preview} package is +@LaTeX{}-dependent. Adding support for other formats requires +volunteers. + +@subsection Does @previewlatex{} work with plain @TeX{}? + +Again, no. Restructuring the @samp{preview} package for @samp{plain} +operation would be required. Volunteers welcome. + +In some cases you might get around by making a wrapper pseudo-Master +file looking like the following: + +@example +\documentclass@{article@} +\usepackage@{plain@} +\begin@{document@} +\begin@{plain@} +\input myplainfile +\end@{plain@} +\end@{document@} +@end example diff --git a/elpa/auctex-13.1.3/doc/preview-latex.texi b/elpa/auctex-13.1.3/doc/preview-latex.texi new file mode 100644 index 0000000..26adb89 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/preview-latex.texi @@ -0,0 +1,849 @@ +\input texinfo +@comment %**start of header +@setfilename preview-latex.info +@include version.texi +@settitle preview-latex @value{VERSION} +@comment %**end of header +@include macros.texi +@copying +This manual is for preview-latex, a @LaTeX{} preview mode for @AUCTeX{} +(version @value{VERSION} from @value{UPDATED}). + +Copyright @copyright{} 2001, 2002, 2003, +2004, 2005, 2006, 2017-2019, 2021 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 +* preview-latex: (preview-latex). Preview LaTeX fragments in Emacs +@end direntry +@dircategory TeX +@direntry +* preview-latex: (preview-latex). Preview LaTeX fragments in Emacs +@end direntry +@c footnotestyle separate +@c paragraphindent 2 +@syncodeindex vr cp +@syncodeindex ky cp +@syncodeindex fn cp + +@iftex +@tolerance 10000 @emergencystretch 3em +@end iftex + +@finalout +@titlepage +@title @previewlatex{} +@subtitle A @LaTeX{} preview mode for @AUCTeX{} in Emacs. +@subtitle Version @value{VERSION}, @value{UPDATED} +@author Jan-@AA{}ke Larsson +@author David Kastrup and others +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c @summarycontents +@contents + +@c Use @ifinfo _and_ @ifhtml here because Texinfo 3 cannot cope with +@c @ifnottex around a top node. +@ifinfo +@node top, , (dir), (dir) +@top @previewlatex{} + +This manual may be copied under the conditions spelled out in +@ref{Copying this Manual}. + +@end ifinfo +@ifhtml +@node top, Copying, (dir), (dir) +@top @previewlatex{} +@insertcopying +@end ifhtml + +@iftex +@unnumbered @previewlatex{} +@end iftex + +@previewlatex{} is a package embedding preview fragments into Emacs +source buffers under the @AUCTeX{} editing environment for @LaTeX{}. It +uses @file{preview.sty} for the extraction of certain environments (most +notably displayed formulas). Other applications of this style file are +possible and exist. + +The name of the package is really @samp{preview-latex}, all in +lowercase letters, with a hyphen. If you typeset it, you can use a +sans-serif font to visually offset it. + +@menu +* Copying:: Copying +* Introduction:: Getting started. +* Installation:: Make Install. +* Keys and lisp:: Key bindings and user-level lisp functions. +* Simple customization:: To make it fit in. +* Known problems:: When things go wrong. +* For advanced users:: Internals and more customizations. +* ToDo:: Future development. +* Frequently Asked Questions:: All about @previewlatex{} +* Copying this Manual:: GNU Free Documentation License +* Index:: A menu of many topics. +@end menu + +@node Copying, Introduction, top, top +@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 + +For the conditions for copying parts of @previewlatex{}, see the General +Public Licenses referred to in the copyright notices of the files, the +General Public Licenses accompanying them and the explanatory section in +@ref{Copying,,,auctex,the @AUCTeX{} manual}. + +This manual specifically is covered by the GNU Free Documentation +License (@pxref{Copying this Manual}). + +@node Introduction, Installation, Copying, top +@c Used as @file{README} as well: in separate file +@chapter Introduction +@include preview-readme.texi + +@node Installation, Keys and lisp, Introduction, top +@chapter Installation +Installation is now being covered in +@ref{Installation,,,auctex,the @AUCTeX{} manual}. + +@node Keys and lisp, Simple customization, Installation, top +@chapter Key bindings and user-level lisp functions + +@cindex Menu entries +@previewlatex{} adds key bindings starting with @kbd{C-c C-p} to the +supported modes of @AUCTeX{} (@xref{Key Index,,,auctex}). It will +also add its own @samp{Preview} menu in the menu bar, as well as an icon +in the toolbar. + +The following only describes the interactive use: view the documentation +strings with @kbd{C-h f} if you need the Lisp information. + +@table @w +@item @kbd{C-c C-p C-p} +@itemx @code{preview-at-point} +@itemx Preview/Generate previews (or toggle) at point +If the cursor is positioned on or inside of a preview area, this +toggles its visibility, regenerating the preview if necessary. If not, +it will run the surroundings through preview. The surroundings include +all areas up to the next valid preview, unless invalid previews occur +before, in which case the area will include the last such preview in +either direction. And overriding any other +action, if a region is active (@code{transient-mark-mode}), it is run +through @code{preview-region}. +@kindex @kbd{C-c C-p C-p} +@findex preview-at-point + +@item @kbd{@key{mouse-2}} +The middle mouse button has a similar action bound to it as +@code{preview-at-point}, only that it knows which preview to apply it to +according to the position of the click. You can click either anywhere +on a previewed image, or when the preview is opened and showing the +source text, you can click on the icon preceding the source text. In +other areas, the usual mouse key action (typically: paste) is not +affected. + +@item @kbd{@key{mouse-3}} +The right mouse key pops up a context menu with several options: +toggling the preview, regenerating it, removing it (leaving the +unpreviewed text), copying the text inside of the preview, and copying +it in a form suitable for copying as an image into a mail or news +article. This is a one-image variant of the following command: + +@item @kbd{C-c C-p C-w} +@itemx @code{preview-copy-region-as-mml} +@itemx Copy a region as MML +@kindex @kbd{C-c C-p C-w} +@findex preview-copy-region-as-mml +This command is also available as a variant in the context menu on the +right mouse button (where the region is the preview that has been +clicked on). It copies the current region into the kill buffer in a +form suitable for copying as a text including images into a mail or news +article using mml-mode (@pxref{Composing,,Composing,emacs-mime,Emacs +MIME}). + +If you regenerate or otherwise kill the preview in its source buffer +before the mail or news gets posted, this will fail. Also you should +generate images you want to send with @code{preview-transparent-border} +@vindex preview-transparent-border +set to @code{nil}, or the images will have an ugly border. +@previewlatex{} detects this condition and asks whether to regenerate +the region with borders switched off. As this is an asynchronous +operation running in the background, you'll need to call this command +explicitly again to get the newly generated images into the kill ring. + +Preview your articles with @code{mml-preview} (on @kbd{C-c C-m P}) +@kindex @kbd{C-c C-m P} +to make sure they look fine. + +@item @kbd{C-c C-p C-e} +@itemx @code{preview-environment} +@itemx Preview/Generate previews for environment +Run preview on @LaTeX{} environment. The environments in +@code{preview-inner-environments} are treated as inner levels so that +for instance, the @code{split} environment in +@code{\begin@{equation@}\begin@{split@}@dots{}\end@{split@}\end@{equation@}} +is properly displayed. If called with a numeric argument, the +corresponding number of outward nested environments is treated as inner +levels. +@kindex @kbd{C-c C-p C-e} +@findex preview-environment + +@item @kbd{C-c C-p C-s} +@itemx @code{preview-section} +@itemx Preview/Generate previews for section +Run preview on this @LaTeX{} section. +@kindex @kbd{C-c C-p C-s} +@findex preview-section + +@item @kbd{C-c C-p C-r} +@itemx @code{preview-region} +@itemx Preview/Generate previews for region +Run preview on current region. +@kindex @kbd{C-c C-p C-r} +@findex preview-region + +@item @kbd{C-c C-p C-b} +@itemx @code{preview-buffer} +@itemx Preview/Generate previews for buffer +Run preview on the current buffer. +@kindex @kbd{C-c C-p C-b} +@findex preview-buffer + +@item @kbd{C-c C-p C-d} +@itemx @code{preview-document} +@itemx Preview/Generate previews for document +Run preview on the current document. +@kindex @kbd{C-c C-p C-d} +@findex preview-document + +@item @kbd{C-c C-p C-c C-p} +@itemx @code{preview-clearout-at-point} +@itemx Preview/Remove previews at point +@kindex @kbd{C-c C-p C-c C-p} +@findex preview-clearout-at-point +Clear out (remove) the previews that are immediately adjacent to point. + +@item @kbd{C-c C-p C-c C-s} +@itemx @code{preview-clearout-section} +@itemx Preview/Remove previews from section +@kindex @kbd{C-c C-p C-c C-s} +@findex preview-clearout-document +Clear out all previews in current section. + +@item @kbd{C-c C-p C-c C-r} +@itemx @code{preview-clearout} +@itemx Preview/Remove previews from region +@kindex @kbd{C-c C-p C-c C-r} +@findex preview-clearout +Clear out all previews in the current region. + +@item @kbd{C-c C-p C-c C-b} +@itemx @code{preview-clearout-buffer} +@itemx Preview/Remove previews from buffer +@kindex @kbd{C-c C-p C-c C-b} +@findex preview-clearout-buffer +Clear out all previews in current buffer. This makes the current buffer +lose all previews. + +@item @kbd{C-c C-p C-c C-d} +@itemx @code{preview-clearout-document} +@itemx Preview/Remove previews from document +@kindex @kbd{C-c C-p C-c C-d} +@findex preview-clearout-document +Clear out all previews in current document. The document consists of +all buffers that have the same master file as the current buffer. This +makes the current document lose all previews. + +@item @kbd{C-c C-p C-f} +@itemx @code{preview-cache-preamble} +@itemx Preview/Turn preamble cache on +@kindex @kbd{C-c C-p C-f} +@findex preview-cache-preamble +Dump a pregenerated format file. For the rest of the session, this file +is used when running on the same master file. Use this if you know your +@LaTeX{} takes a long time to start up, the speedup will be most +noticeable when generating single or few previews. If you change your +preamble, do this again. @previewlatex{} will try to detect the +necessity of that automatically when editing changes to the preamble are +done from within Emacs, but it will not notice if the preamble +effectively changes because some included file or style file is +tampered with. + +Note that support for preamble cache is limited for @LaTeX{} variants. +c.f.@: @url{https://github.com/davidcarlisle/dpctex/issues/15} +@itemize @bullet +@item +Xe@LaTeX{} cannot use preamble cache at all. The reason is intrinsic in +Xe@LaTeX{}, so @previewlatex{} can't help. +@item +Lua@LaTeX{} works with preamble cache only when the preamble is simple +enough, i.e., when it doesn't load opentype fonts and it doesn't use lua +codes in preamble. +@end itemize + +@item @kbd{C-c C-p C-c C-f} +@itemx @code{preview-cache-preamble-off} +@itemx Preview/Turn preamble cache off +@kindex @kbd{C-u C-c C-p C-f} +@findex preview-cache-preamble-off +Clear the pregenerated format file and stop using preambles for the +current document. If the caching gives you problems, use this. + +@item @kbd{C-c C-p C-i} +@itemx @code{preview-goto-info-page} +@itemx Preview/Read Documentation +@kindex @kbd{C-c C-p C-i} +@findex preview-goto-info-page +Read +@ifinfo +this +@end ifinfo +@ifnotinfo +the +@end ifnotinfo +info manual. + +@item @kbd{M-x preview-report-bug @key{RET}} +@itemx @code{preview-report-bug} +@itemx Preview/Report Bug +@kindex @kbd{M-x preview-report-bug @key{RET}} +@findex preview-report-bug +@cindex Report a bug +This is the preferred way of reporting bugs as it will fill in what +version of @previewlatex{} you are using as well as versions of +relevant other software, and also some of the more important +settings. Please use this method of reporting, if at all possible and +before reporting a bug, have a look at @ref{Known problems}. + +@item @kbd{C-c C-k} +@itemx LaTeX/TeX Output/Kill Job +@kindex @kbd{C-c C-k} +@cindex Kill preview-generating process +Kills the preview-generating process. This is really an @AUCTeX{} +keybinding, but it is included here as a hint. If you are generating +a preview and then make a change to the buffer, @previewlatex{} may be +confused and place the previews wrong. +@end table + +@node Simple customization, Known problems, Keys and lisp, top +@chapter Simple customization + +Customization options can be found by typing @kbd{M-x customize-group +@key{RET} preview @key{RET}}. Remember to set the option when you have +changed it. The list of suggestions can be made very long (and is +covered in detail in @ref{For advanced users}), but some are: + +@itemize @bullet +@item Change the color of the preview background + +If you use a non-white background in Emacs, you might have color +artifacts at the edges of your previews. Playing around with the option +@code{preview-transparent-color} in the @samp{Preview Appearance} group +might improve things. With some settings, the cursor may cover the +whole background of a preview, however. + +This option is specific to the display engine in use. + +@item Showing @code{\label}s +@cindex Showing @code{\label}s + +When using @previewlatex{}, the @code{\label}s are hidden by the +previews. It is possible to make them visible in the output +by using the @LaTeX{} package @code{showkeys} alternatively +@code{showlabels}. However, the boxes of these labels will be outside +the region @previewlatex{} considers as the preview image. To enable a +similar mechanism internal to @previewlatex{}, enable the +@code{showlabels} option in the variable +@code{preview-default-option-list} in the @samp{Preview Latex} group. +@vindex preview-default-option-list + +It must be noted, however, that a much better idea may be to use the +Ref@TeX{} package for managing references. @xref{RefTeX in a +Nutshell,,RefTeX in a Nutshell,reftex,The Ref@TeX{} Manual}. + +@item Open previews automatically + +The current default is to open previews automatically when you enter +them with cursor left/right motions. Auto-opened previews will close +again once the cursor leaves them again (this is also done when doing +incremental search, or query-replace operations), unless you changed +anything in it. In that case, you will have to regenerate the preview +(via e.g., @kbd{C-c C-p C-p}). Other options for +@code{preview-auto-reveal} are available via @code{customize}. + +@item Automatically cache preambles + +Currently @previewlatex{} asks you whether you want to cache the +document preamble (everything before @code{\begin@{document@}}) before +it generates previews for a buffer the first time. Caching the preamble +will significantly speed up regeneration of previews. The larger your +preamble is, the more this will be apparent. Once a preamble is cached, +@previewlatex{} will try to keep track of when it is changed, and dump +a fresh format in that case. If you experience problems with this, or +if you want it to happen without asking you the first time, you can +customize the variable @code{preview-auto-cache-preamble}. +@vindex preview-auto-cache-preamble +@cindex Caching a preamble + +@item Attempt to keep counters accurate when editing + +@vindex preview-preserve-counters +@vindex preview-required-option-list +Since @previewlatex{} frequently runs only small regions through +@LaTeX{}, values like equation counters are not consistent from run to +run. If this bothers you, customize the variable +@code{preview-preserve-counters} to @code{t} (this is consulted by +@code{preview-required-option-list}). @LaTeX{} will then output a load +of counter information during compilation, and this information will be +used on subsequent updates to keep counters set to useful values. The +additional information takes additional time to analyze, but this is +relevant mostly only when you are regenerating all previews at once, and +maybe you will be less tempted to do so when counters appear more or +less correct. + +@item Preview your favourite @LaTeX{} constructs + +@vindex preview-default-option-list +@vindex preview-default-preamble +If you have a certain macro or environment that you want to preview, +first check if it can be chosen by cutomizing +@code{preview-default-option-list} in the @samp{Preview Latex} group. + +If it is not available there, you can add it to +@code{preview-default-preamble} also in the @samp{Preview Latex} group, +by adding a @code{\PreviewMacro} or @code{\PreviewEnvironment} entry +(@pxref{Provided commands}) @emph{after} the @code{\RequirePackage} +line. For example, if you want to preview the @code{center} +environment, press the @key{Show} button and the last @key{INS} button, +then add + +@example +\PreviewEnvironment@{center@} +@end example +@noindent +in the space that just opened. Note that since @code{center} is a +generic formatting construct of @LaTeX{}, a general configuration like +that is not quite prudent. You better to do this on a per-document +base so that it is easy to disable this behavior when you find this +particular entry gives you trouble. + +One possibility is to save such settings in the corresponding file-local +variable instead of your global configuration (@pxref{File +Variables,,Local Variables in Files,emacs,GNU Emacs Manual}). A perhaps +more convenient place for such options would be in a configuration file +in the same directory with your project (@pxref{Package options}). + +The usual file for @previewlatex{} preconfiguration is +@file{prauctex.cfg}. If you also want to keep the systemwide defaults, +you should add a line + +@example +\InputIfFileExists@{preview/prauctex.cfg@}@{@}@{@} +@end example +@noindent +to your own version of @file{prauctex.cfg} (this is assuming that +global files relating to the @code{preview} package are installed in a +subdirectory @file{preview}, the default behavior). + +@item Don't preview inline math +@cindex Inline math +@vindex preview-default-option-list + +If you have performance problems because your document is full of inline +math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with +@previewlatex{}'s, you can turn off inline math previews. In the +@samp{Preview Latex} group, remove @code{textmath} from +@code{preview-default-option-list} by customizing this variable. +@end itemize + +@node Known problems, For advanced users, Simple customization, top +@chapter Known problems +@c also used as PROBLEMS file +@include preview-problems.texi + +@node For advanced users, ToDo, Known problems, top +@chapter For advanced users + +This package consists of two parts: a @LaTeX{} style that splits the +output into appropriate parts with one preview object on each page, and +an Emacs-lisp part integrating the thing into Emacs (aided by +@AUCTeX{}). + +@menu +* The LaTeX style file:: +* The Emacs interface:: +* The preview images:: +* Misplaced previews:: +@end menu + +@node The LaTeX style file, The Emacs interface, For advanced users, For advanced users +@section The @LaTeX{} style file +@c Autogenerated from ../latex/preview.dtx +@include preview-dtxdoc.texi + +@node The Emacs interface, The preview images, The LaTeX style file, For advanced users +@section The Emacs interface + +You can use @kbd{M-x customize-group @key{RET} preview-latex @key{RET}} +in order to customize these variables, or use the menus for it. We +explain the various available options together with explaining how they +work together in making @previewlatex{} work as intended. + +@vtable @code +@item preview-LaTeX-command +When you generate previews on a buffer or a region, the command in +@code{preview-LaTeX-command} gets run (that variable should only be +changed with Customize since its structure is somewhat peculiar, though +expressive). As usual with @AUCTeX{}, you can continue working while +this is going on. It is not a good idea to change the file until after +@previewlatex{} has established where to place the previews which it can +only do after the @LaTeX{} run completes. This run produces a host of +pseudo-error messages that get parsed by @previewlatex{} at the end of +the @LaTeX{} run and give it the necessary information about where in +the source file the @LaTeX{} code for the various previews is located +exactly. The parsing takes a moment and will render Emacs busy. + +@item preview-LaTeX-command-replacements +This variable specifies transformations to be used before calling the +configured command. One possibility is to have @samp{\pdfoutput=0 } +appended to every command starting with @samp{pdf}. This particular +setting is available as the shortcut +@code{preview-LaTeX-disable-pdfoutput}. Since @previewlatex{} can work +with @acronym{PDF} files by now, there is little incentive for using +this option, anymore (for projects not requiring @acronym{PDF} output, +the added speed of @command{dvipng} might make this somewhat attractive). + +@item preview-required-option-list +@code{preview-LaTeX-command} uses @code{preview-required-option-list} in +order to pass options such as @option{auctex}, @option{active} and +@option{dvips} to the @file{preview} package. This means that the user +need (and should) not supply these in the document itself in case he +wants to be able to still compile his document without it turning into +an incoherent mass of little pictures. These options even get passed +in when the user loads @file{preview} explicitly in his document. + +The default includes an option @code{counters} that is controlled by the +boolean variable + +@item preview-preserve-counters +This option will cause the @file{preview} package to emit information +that will assist in keeping things like equation counters and section +numbers reasonably correct even when you are regenerating only single +previews. + +@item preview-default-option-list +@itemx preview-default-preamble +If the document does not call in the package @code{preview} itself (via +@code{\usepackage}) in the preamble, the preview package is loaded using +default options from @code{preview-default-option-list} and additional +commands specified in @code{preview-default-preamble}. + +@item preview-fast-conversion +This is relevant only for @acronym{DVI} mode. It defaults to `On' and +results in the whole document being processed as one large PostScript +file from which the single images are extracted with the help of parsing +the PostScript for use of so-called @acronym{DSC} comments. The +bounding boxes are extracted with the help of @TeX{} instead of getting +them from Dvips. If you are experiencing bounding box problems, try +setting this option to `Off'. + +@item preview-prefer-TeX-bb +If this option is `On', it tells @previewlatex{} never to try to extract +bounding boxes from the bounding box comments of @acronym{EPS} files, +but rather rely on the boxes it gets from @TeX{}. If you activated +@code{preview-fast-conversion}, this is done, anyhow, since there are no +@acronym{EPS} files from which to read this information. The option +defaults to `Off', simply because about the only conceivable reason to +switch off @code{preview-fast-conversion} would be that you have some +bounding box problem and want to get Dvips' angle on that matter. + +@item preview-scale-function +@itemx preview-reference-face +@itemx preview-document-pt-list +@itemx preview-default-document-pt +@code{preview-scale-function} determines by what factor +images should be scaled when appearing on the screen. If you specify a +numerical value here, the physical size on the screen will be that of +the original paper output scaled by the specified factor, at least if +Emacs' information about screen size and resolution are correct. The +default is to let @code{preview-scale-from-face} determine the scale +function. This function determines the scale factor by making the +size of the default font in the document match that of the on-screen +fonts. + +The size of the screen fonts is deduced from the font +@code{preview-reference-face} (usually the default face used for +display), the size of the default font for the document is determined +by calling @code{preview-document-pt}. +@findex preview-document-pt +This function consults the members of @code{preview-document-pt-list} in +turn until it gets the desired information. The default consults first +@code{preview-parsed-font-size}, +@vindex preview-parsed-font-size +then calls @code{preview-auctex-font-size} +@findex preview-auctex-font-size +which asks @AUCTeX{} about any size specification like @option{12pt} to +the documentclass that it might have detected when parsing the document, and +finally reverts to just assuming @code{preview-default-document-pt} as +the size used in the document (defaulting to 10pt). + +If you find that the size of previews and the other Emacs display +clashes, something goes wrong. @code{preview-parsed-font-size} is +determined at @code{\begin@{document@}} time; if the default font size +changes after that, it will not get reported. If you have an outdated +version of @file{preview.sty} in your path, the size might not be +reported at all. If in this case @AUCTeX{} is unable to find a size +specification, and if you are using a document class with a different +default value (like @samp{KomaScript}), the default fallback assumption will +probably be wrong and @previewlatex{} will scale up things too large. +So better specify those size options even when you know that @LaTeX{} +does not need them: @previewlatex{} might benefit from them. Another +possibility for error is that you have not enabled @AUCTeX{}'s document +parsing options. The fallback method of asking @AUCTeX{} about the size +might be disabled in future versions of @previewlatex{} since in +general it is more reliable to get this information from the @LaTeX{} +run itself. + +@item preview-fast-dvips-command +@itemx preview-dvips-command +The regular command for turning a @acronym{DVI} file into a single +PostScript file is @code{preview-fast-dvips-command}, while +@code{preview-dvips-command} is used for cranking out a @acronym{DVI} +file where every preview is in a separate @acronym{EPS} file. Which of +the two commands gets used depends on the setting of +@code{preview-fast-conversion}. The printer specified here +is @option{-Pwww} by default, which will usually get you scalable fonts +where available. If you are experiencing problems, you might want to try +playing around with Dvips options (@xref{Command-line options,,,dvips}). + +The conversion of the previews into PostScript or @acronym{EPS} files +gets started after the @LaTeX{} run completes when Emacs recognizes the +first image while parsing the error messages. When Emacs has finished +parsing the error messages, it activates all detected previews. This +entails throwing away any previous previews covering the same areas, and +then replacing the text in its visual appearance by a placeholder +looking like a roadworks sign. + +@item preview-nonready-icon-specs +This is the roadworks sign displayed while previews are being prepared. +You may want to customize the font sizes at which @previewlatex{} +switches over between different icon sizes, and the ascent ratio which +determines how high above the base line the icon gets placed. + +@item preview-error-icon-specs +@itemx preview-icon-specs +Those are icons placed before the source code of an opened preview and, +respectively, the image specs to be used for PostScript errors, and a +normal open preview in text representation. + +@item preview-inner-environments +This is a list of environments that are regarded as inner levels of an +outer environment when doing @code{preview-environment}. One example +when this is needed is in +@code{\begin@{equation@}\begin@{split@}@dots{}\end@{split@}\end@{equation@}}, and +accordingly @code{split} is one entry in +@code{preview-inner-environments}. + +@end vtable + +@node The preview images, Misplaced previews, The Emacs interface, For advanced users +@section The preview images + +@vtable @code +@item preview-image-type +@itemx preview-image-creators +@itemx preview-gs-image-type-alist +What happens when @LaTeX{} is finished depends on the configuration of +@code{preview-image-type}. What to do for each of the various settings +is specified in the variable @code{preview-image-creators}. The options +to pass into Ghostscript and what Emacs image type to use is specified +in @code{preview-gs-image-type-alist}. + +@code{preview-image-type} defaults to @code{png}. For this to work, +your version of Ghostscript needs to support the @option{png16m} device. +If you are experiencing problems here, you might want to reconfigure +@code{preview-gs-image-type-alist} or @code{preview-image-type}. Reconfiguring +@code{preview-image-creators} is only necessary for adding additional +image types. + +Most devices make @previewlatex{} start up a single Ghostscript process +for the entire preview run (as opposed to one per image) and feed it +either sections of a @acronym{PDF} file (if PDF@LaTeX{} was used), or +(after running Dvips) sections of a single PostScript file or separate +@acronym{EPS} files in sequence for conversion into @acronym{PNG} format +which can be displayed much faster by Emacs. Actually, not in sequence +but backwards since you are most likely editing at the end of the +document. And as an added convenience, any preview that happens to be +on-screen is given higher priority so that @previewlatex{} will first +cater for the images that are displayed. There are various options +customizable concerning aspects of that operation, see the customization +group @samp{Preview Gs} for this. + +Another noteworthy setting of @code{preview-image-type} is +@samp{dvipng}: in this case, the @command{dvipng} +@pindex dvipng +program will get run on @acronym{DVI} output (see below for @acronym{PDF}). +This is in general much faster than Dvips and Ghostscript. In that +case, the option + +@item preview-dvipng-command +will get run for doing the conversion, and it is expected that + +@item preview-dvipng-image-type +images get produced (@samp{dvipng} might be configured for other image +types as well). You will notice that @code{preview-gs-image-type-alist} +contains an entry for @code{dvipng}: this actually has nothing to with +@samp{dvipng} itself but specifies the image type and Ghostscript device +option to use when @samp{dvipng} can't be used. This will obviously be +the case for @acronym{PDF} output by PDF@LaTeX{}, but it will also happen +if the @acronym{DVI} file contains PostScript specials in which case the +affected images will get run through Dvips and Ghostscript once +@samp{dvipng} finishes. + +Note for p@LaTeX{} and up@LaTeX{} users: It is known that @command{dvipng} +is not compatible with p@LaTeX{} and up@LaTeX{}. If +@code{preview-image-type} is set to @samp{dvipng} and (u)p@LaTeX{} is +used, @samp{dvipng} just fails and @previewlatex{} falls back on Dvips +and Ghostscript. + +@item preview-gs-options +Most interesting to the user perhaps is the setting of this variable. +It contains the default antialiasing settings @option{-dTextAlphaBits=4} +and @option{-dGraphicsAlphaBits=4}. Decreasing those values to 2 @w{or +1} might increase Ghostscript's performance if you find it lacking. +@end vtable + +Running and feeding Ghostscript from @previewlatex{} happens +asynchronously again: you can resume editing while the images arrive. +While those pretty pictures filling in the blanks on screen tend to +make one marvel instead of work, rendering the non-displayed images +afterwards will not take away your attention and will eventually +guarantee that jumping around in the document will encounter only +prerendered images. + +@node Misplaced previews, , The preview images, For advanced users +@section Misplaced previews + +If you are reading this section, the first thing is to check that your +problem is not caused by x-symbol in connection with an installation not +supporting 8-bit characters (@pxref{x-symbol interoperation}). If not, +here's the beef: + +As explained previously, Emacs uses pseudo-error messages generated by +the @samp{preview} package in order to pinpoint the exact source +location where a preview originated. This works in running text, but +fails when preview material happens to lie in macro arguments, like the +contents of @code{\emph}. Those macros first read in their entire +argument, munge it through, perhaps transform it somehow, process it and +perhaps then typeset something. When they finally typeset something, +where is the location where the stuff originated? @TeX{}, having read in +the entire argument before, does not know and actually there would be no +sane way of defining it. + +For previews contained inside such a macro argument, the default +behaviour of @previewlatex{} is to use a position immediately after the +closing brace of the argument. All the previews get placed there, all at +a zero-width position, which means that Emacs displays it in an order +that @previewlatex{} cannot influence (currently in Emacs it is even +possible that the order changes between runs). And since the placement +of those previews is goofed up, you will not be able to regenerate them +by clicking on them. The default behaviour is thus somewhat undesirable. + +The solution (like with other preview problems) is to tell the @LaTeX{} +@samp{preview} package how to tackle this problem (@pxref{The LaTeX +style file}). Simply, you don't need @code{\emph} do anything at all +during previews! You only want the text math previewed, so the solution +is to use @code{\PreviewMacro*\emph} in the preamble of your document +which will make @LaTeX{} ignore @code{\emph} completely as long as it is +not part of a larger preview (in which case it gets typeset as +usual). Its argument thus becomes ordinary text and gets treated like +ordinary text. + +Note that it would be a bad idea to declare +@code{\PreviewMacro*[@{@{@}@}]\emph} since then both @code{\emph} as +well as its argument would be ignored instead of previewed. For +user-level macros, this is almost never wanted, but there may be +internal macros where you might want to ignore internal arguments. + +The same mechanism can be used for a number of other text-formatting +commands like @code{\textrm}, @code{\textit} and the like. While they +all use the same internal macro @code{\text@@command}, it will not do to +redefine just that, since they call it only after having read their +argument in, and then it already is too late. So you need to disable +every of those commands by hand in your document preamble. + +Actually, we wrote all of the above just to scare you. At least all of +the above mentioned macros and a few more are already catered for by a +configuration file @file{prauctex.cfg} that gets loaded by default +unless the @samp{preview} package gets loaded with the @option{noconfig} +option. You can make your own copy of this file in a local directory +and edit it in case of need. You can also add loading of a file of your +liking to @code{preview-default-preamble}, +@vindex preview-default-preamble +or alternatively do the +manual disabling of your favorite macro in +@code{preview-default-preamble}, +@vindex preview-default-preamble +which is customizable in the @samp{Preview Latex} group. + +@node ToDo, Frequently Asked Questions, For advanced users, top +@c Also used as TODO: in separate file +@appendix ToDo +@include preview-todo.texi + +@node Frequently Asked Questions, Copying this Manual, ToDo, top +@c Also used as TODO: in separate file +@appendix Frequently Asked Questions +@include preview-faq.texi + +@node Copying this Manual, Index, Frequently Asked Questions, top +@c Not to be changed often, I think: in separate file. +@appendix 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 + +@include fdl.texi + +@c @node Credits, Index, Internals, top +@c @appendix Credits + +@node Index, , Copying this Manual, top +@unnumbered Index + +@printindex cp + +@bye diff --git a/elpa/auctex-13.1.3/doc/preview-problems.texi b/elpa/auctex-13.1.3/doc/preview-problems.texi new file mode 100644 index 0000000..e40ff42 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/preview-problems.texi @@ -0,0 +1,196 @@ +@include macros.texi +@ifset rawfile +@c documentencoding is used by makeinfo in our --no-headers output. +@documentencoding ISO-8859-1 +@node Known problems,,(dir),(dir) +@top Known problems with preview-latex + +@end ifset +@c ----------------------- +@c @cindex @kbd{M-x preview-report-bug @key{RET}} +@c @cindex @code{preview-report-bug} +@c @cindex Report a bug +A number of issues are known concerning the interoperation with various +other software. Some of the known problems can be solved by moving to +newer versions of the problematic software or by simple patches. + +@menu +* Font problems with Dvips:: +* Too small bounding boxes:: +* x-symbol interoperation:: +* Middle-clicks paste instead of toggling:: +* No images are displayed with gs 9.27 and earlier:: +@end menu + +If you find something not mentioned here, please send a bug report using +@kbd{M-x preview-report-bug @key{RET}}, which will fill in a lot of +information interesting to us and send it to the +@email{bug-auctex@@gnu.org} list. Please use the bug reporting commands +if at all possible. + +@ifset rawfile +@node Font problems with Dvips +@chapter Font problems with Dvips +@raisesections +@end ifset +@ifclear rawfile +@node Font problems with Dvips +@section Font problems with Dvips +@end ifclear + +Some fonts have been reported to produce wrong characters with +@previewlatex{}. @previewlatex{} calls Dvips by default with the option +@option{-Pwww} in order to get scalable fonts for nice results. If you +are using antialiasing, however, the results might be sufficiently nice +with bitmapped fonts, anyway. You might try @option{-Ppdf} for another +stab at scalable fonts, or other printer definitions. Use + +@display +@kbd{M-x customize-option @key{RET} preview-fast-dvips-command @key{RET}} +@end display +@noindent +and +@display +@kbd{M-x customize-option @key{RET} preview-dvips-command @key{RET}} +@end display +@noindent +in order to customize this. + +One particular problem is that several printer setup files (typically in +a file called @file{/usr/share/texmf/dvips/config/config.pdf} if you are +using the @option{-Ppdf} switch) contain the @option{G} option for +`character shifting'. This option will result in @samp{fi} being +rendered as @samp{@pounds{}} (British Pounds sign) in several fonts, +unless your version of Dvips has a long-standing bug in its +implementation fixed (only very recent versions of Dvips have). + +@node Too small bounding boxes +@section Too small bounding boxes +The bounding box of a preview is determined by the @LaTeX{} package +using the pure @TeX{} bounding boxes. If there is material extending +outside of the @TeX{} box, that material will be missing from the +preview image. This happens for the label-showing boxes from +the @code{showkeys} package. This particular problem can be +circumvented by using the @code{showlabels} option of the preview +package. + +In general, you should try to fix the problem in the @TeX{} code, like +avoiding drawing outside of the picture with PSTricks. + +One possible remedy is to set +@code{preview-fast-conversion} to `Off' +@ifset rawfile +(see the manual). +@end ifset +@ifclear rawfile +(@pxref{The Emacs interface}). +@end ifclear +The conversion will take more time, but will then use the bounding boxes +from @acronym{EPS} files generated by Dvips. + +Dvips generally does not miss things, but it does not understand +PostScript constructs like @code{\resizebox} or @code{\rotate} commands, +so will generate rather wrong boxes for those. Dvips can be helped with +the @code{psfixbb} package option to preview +@ifset rawfile +(see the manual), +@end ifset +@ifclear rawfile +(@pxref{The LaTeX style file}), +@end ifclear +which will tag the corners of the included @TeX{} box. This will mostly +be convenient for @emph{pure} PostScript stuff like that created by +PSTricks, which Dvips would otherwise reserve no space for. + +@c FIXME: It seems that x-symbol is much outdated. +@node x-symbol interoperation +@section x-symbol interoperation + +Thanks to the work of Christoph Wedler, starting with version +@samp{4.0h/beta} of x-symbol, the line parsing of @AUCTeX{} and +@previewlatex{} is fully supported. Earlier versions exhibit problems. +However, versions before @samp{4.2.2} will cause a drastic slowdown of +@previewlatex{}'s parsing pass, so we don't recommend to use versions +earlier than that. + +If you wonder what x-symbol is, it is a package that transforms various +tokens and subscripts to a more readable form while editing and offers a +few input methods handy especially for dealing with math. Take a look at +@uref{http://x-symbol.sourceforge.net/}. + +x-symbol versions up to @samp{4.5.1-beta} at least require an 8bit-clean @TeX{} +implementation (meaning that its terminal output should not use +@samp{^^}-started escape sequences) for cooperation with +@previewlatex{}. Later versions may get along without it, like +@previewlatex{} does now. + +If you experience problems with @file{circ.tex} in connection with both +x-symbol and Latin-1 characters, you may need to change your language +environment or, as a last resort, customize the variable +@code{LaTeX-command-style} by replacing the command @code{latex} with +@code{latex -translate-file=cp8bit}. + +@node Middle-clicks paste instead of toggling +@section Middle-clicks paste instead of toggling + +This is probably the fault of your favorite package. @file{isearch.el} +is known to be affected while searches are in progress, but the code is +such a complicated mess that no patch is in sight. Better just end the +search with @kbd{@key{RET}} before toggling and resume with @kbd{C-s +C-s} or similar afterwards. Since previews over the current match will +auto-open, anyway, this should not be much of a problem in practice. + +@node No images are displayed with gs 9.27 and earlier +@section No images are displayed with gs 9.27 and earlier + +@previewlatex{} tries to adjust the foreground and background colors of +generated images to those of Emacs. Unfortunately, incompatible changes +introduced in Ghostscript 9.27 breaks the traditional method partially, +and @previewlatex{} can display no images under certain circumstances. + +A new method implemented alternatively works only with Ghostscript > +9.27. If you are using Ghostscript 9.27 or earlier, customize the +option @code{preview-pdf-adjust-color-method}. + +@defopt preview-pdf-adjust-color-method +Method to adjust colors of images generated from @acronym{PDF}. It is +not consulted when the @LaTeX{} command produces @acronym{DVI} files. + +When the option is @code{t} (default), @previewlatex{} adjusts the FG +and BG colors of the generated images by the new method. This method +requires that Ghostscript has working @code{DELAYBIND} feature, thus is +invalid with gs 9.27 (and possibly < 9.27). + +When it is @code{compatible}, @previewlatex{} uses traditional method. +This option is provided for backward compatibility with older gs. See +the below explanation for detail. + +When @code{nil}, no adjustment is done and ``black on white'' image is +generated regardless of Emacs color. This is provided for fallback for +gs 9.27 users with customized foreground color. See the below +explanation for detail. + +When the @LaTeX{} command produces @acronym{PDF} rather than +@acronym{DVI} and Emacs has non-trivial foreground color, the +traditional method (@code{compatible}) makes gs >= 9.27 to stop with +error. Here, ``non-trivial foreground color'' includes customized +themes. + +If you use such non-trivial foreground color and the version of +Ghostscript equals to 9.27, you have two options: +@enumerate +@item +Choose the value @code{compatible} and customize +@code{preview-reference-face} to have default (black) foreground color. +This makes the generated image almost non-readable on dark background, +so the next option would be your only choice in that case. +@item +Choose the value @code{nil}, which forces plain ``black on white'' +appearance for the generated image. You can at least read what are +written in the image although they may not match with your Emacs color +well. +@end enumerate + +The default value used to be @code{compatible} for short period before +Ghostscript 9.50 was released but now is @code{t}. +@end defopt diff --git a/elpa/auctex-13.1.3/doc/preview-readme.texi b/elpa/auctex-13.1.3/doc/preview-readme.texi new file mode 100644 index 0000000..8d4c565 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/preview-readme.texi @@ -0,0 +1,229 @@ +@include macros.texi +@ifset rawfile +@node Introduction, What use is it?, (dir), (dir) +@top @previewlatex{} in a nutshell +@paragraphindent none +@end ifset +@c ----------------------- +@cindex Readme +Does your neck hurt from turning between previewer windows and the +source too often? This @AUCTeX{} component will render your displayed +@LaTeX{} equations right into the editing window where they belong. + +The purpose of @previewlatex{} is to embed @LaTeX{} environments such as +display math or figures into the source buffers and switch conveniently +between source and image representation. + +@menu +* What use is it?:: +* Activating preview-latex:: +* Getting started:: +* Basic modes of operation:: +* More documentation:: +* Availability:: +* Contacts:: +@end menu + +@ifset rawfile +@node What use is it?, Activating preview-latex, Introduction, Introduction +@chapter What use is it? +@raisesections +@end ifset +@ifclear rawfile +@node What use is it?, Activating preview-latex, Introduction, Introduction +@section What use is it? +@end ifclear +@cindex Philosophy of @previewlatex{} +@acronym{WYSIWYG} (what you see is what you get) sometimes is considered +all the rage, sometimes frowned upon. Do we really want it? Wrong +question. The right question is @emph{what} we want from it. Except +when finetuning the layout, we don't want to use printer fonts for +on-screen text editing. The low resolution and contrast of a computer +screen render all but the coarsest printer fonts (those for low-quality +newsprint) unappealing, and the margins and pagination of the print are +not wanted on the screen, either. On the other hand, more complex +visual compositions like math formulas and tables can't easily be taken +in when seen only in the source. @previewlatex{} strikes a balance: it +only uses graphic renditions of the output for certain, configurable +constructs, does this only when told, and then right in the source code. +Switching back and forth between the source and preview is easy and +natural and can be done for each image independently. Behind the scenes +of @previewlatex{}, a sophisticated framework of other programs like +@samp{dvipng}, Dvips and Ghostscript are employed together with a +special @LaTeX{} style file for extracting the material of interest in +the background and providing fast interactive response. + +@node Activating preview-latex, Getting started, What use is it?, Introduction +@section Activating @previewlatex{} +@cindex Activation +After installation, the package may need to be activated (and remember +to activate @AUCTeX{} too). If @previewlatex{} is installed via the +Emacs package manager (@acronym{ELPA}), activation should be automatic +upon installation. + +The usual activation (if it is not done automatically) would be + +@example +(load "preview-latex.el" nil t t) +@end example + +If you still don't get a ``Preview'' menu in @LaTeX{} mode in spite +of @AUCTeX{} showing its ``Command'', your installation is broken. One +possible cause are duplicate Lisp files that might be detectable with +@kbd{M-x list-load-path-shadows @key{RET}}. + +@node Getting started, Basic modes of operation, Activating preview-latex, Introduction +@section Getting started + +Once activated, @previewlatex{} and its documentation will be accessible +via its menus (note that @previewlatex{} requires @AUCTeX{} to be +loaded). When you have loaded a @LaTeX{} document (a +sample document @file{circ.tex} is included in the distribution, but +most documents including math and/or figures should do), you can use +its menu or @kbd{C-c C-p C-d} (for @samp{Preview/Document}). +Previews will now be generated for various objects in your document. +You can use the time to take a short look at the other menu entries and +key bindings in the @samp{Preview} menu. You'll see the previewed +objects change into a roadworks sign when @previewlatex{} has determined +just what it is going to preview. Note that you can freely navigate the +buffer while this is going on. When the process is finished you will +see the objects typeset in your buffer. + +It is a bad idea, however, to edit the buffer before the roadworks signs +appear, since that is the moment when the correlation between the +original text and the buffer locations gets established. If the buffer +changes before that point of time, the previews will not be placed where +they belong. If you do want to change some obvious error you just +spotted, we recommend you stop the background process by pressing +@kbd{C-c C-k}. + +To see/edit the @LaTeX{} code for a specific object, put the point (the +cursor) on it and press @kbd{C-c C-p C-p} (for @samp{Preview/at point}). +It will also do to click with the middle mouse button on the preview. +Now you can edit the code, and generate a new preview by again pressing +@kbd{C-c C-p C-p} (or by clicking with the middle mouse button on the +icon before the edited text). + +If you are using the @code{desktop} package, previews will remain from +one session to the next as long as you don't kill your buffer. + +@node Basic modes of operation, More documentation, Getting started, Introduction +@section Basic modes of operation + +@previewlatex{} has a number of methods for generating its graphics. +Its default operation is equivalent to using the `@LaTeX{}' command from +@AUCTeX{}. If this happens to be a call of PDF@LaTeX{} generating +@acronym{PDF} output (you need at least @w{@AUCTeX{} 11.51} for this), +then Ghostscript will be called directly on the resulting @acronym{PDF} +file. If a @acronym{DVI} file gets produced, first Dvips and then +Ghostscript get called by default. + +The image type to be generated by Ghostscript can be configured with + +@example +@kbd{M-x customize-option @key{RET} preview-image-type @key{RET}} +@end example +@vindex preview-image-type + +@noindent +The default is @samp{png} (the most efficient image type). A special +setting is @samp{dvipng} in case you have the @samp{dvipng} +@cindex Using dvipng +@pindex dvipng +program installed. In this case, @samp{dvipng} will be used for +converting @acronym{DVI} files and Ghostscript (with a @samp{PNG} +device) for converting @acronym{PDF} files. @samp{dvipng} is much +faster than the combination of Dvips and Ghostscript. You can get +downloads, access to its @acronym{CVS} archive and further information +from its @uref{https://savannah.nongnu.org/projects/dvipng, project +site}. + +@node More documentation, Availability, Basic modes of operation, Introduction +@section More documentation +After the installation, documentation in the form of +@ifinfo +@ifclear rawfile +this +@end ifclear +@ifset rawfile +an +@end ifset +@end ifinfo +@ifnotinfo +an +@end ifnotinfo +info manual will be available. You can access it with the standalone +info reader with + +@example +info preview-latex +@end example + +@noindent +or by pressing @kbd{C-h i d m preview-latex @key{RET}} in Emacs. Once +@previewlatex{} is activated, you can instead use @kbd{C-c C-p +@key{TAB}} (or the menu entry @samp{Preview/Read documentation}). + +Depending on your installation, +@ifnottex +a printable +@end ifnottex +@iftex +this printed +@end iftex +manual may also be available in the form of @file{preview-latex.pdf}. + +Detailed documentation for the @LaTeX{} style used for extracting the +preview images is placed in @file{preview.pdf} in a suitable directory +during installation; on typical @w{@TeX{} Live}-based systems, + +@example +texdoc preview +@end example + +@noindent +will display it. + +@node Availability, Contacts, More documentation, Introduction +@section Availability +@cindex Download +@cindex @sc{git} access + +The @previewlatex{} project is now part of @AUCTeX{} and accessible as +part of the @uref{https://savannah.gnu.org/projects/auctex,@AUCTeX{} +project page}. You can get its files from the +@uref{https://ftp.gnu.org/pub/gnu/auctex/,@AUCTeX{} download area}. As of +@w{@AUCTeX{} 11.81}, @previewlatex{} should already be integrated into +@AUCTeX{}, so no separate download will be necessary. + +Anonymous Git is available at @uref{git://git.savannah.gnu.org/auctex.git} +or @uref{https://git.savannah.gnu.org/git/auctex.git}. You can also +@uref{https://git.savannah.gnu.org/cgit/auctex.git,browse the repository} +via web interface. + +@node Contacts, , Availability, Introduction +@section Contacts +@cindex Contacts +@cindex Mailing list + +Bug reports should be sent by using @kbd{M-x preview-report-bug +@key{RET}}, as this will fill in a lot of information interesting to +us. If the installation fails (but this should be a rare event), report +bugs to @email{bug-auctex@@gnu.org}. + +There is a general discussion list for @AUCTeX{} which also +covers @previewlatex{}, look at +@uref{https://lists.gnu.org/mailman/listinfo/auctex}. For more +information on the mailing list, send a message with just the word +``help'' as subject or body to @email{auctex-request@@gnu.org}. For the +developers, there is the @email{auctex-devel@@gnu.org} list; it would +probably make sense to direct feature requests and questions about +internal details there. There is a low-volume read-only announcement +list available to which you can subscribe by sending a mail with +``subscribe'' in the subject to @email{info-auctex-request@@gnu.org}. + +Offers to support further development will be appreciated. If you want +to show your appreciation with a donation to the main developer, you can +do so via PayPal to @email{dak@@gnu.org}, and of course you can arrange +for service contracts or for added functionality. Take a look at the +@file{TODO} list for suggestions in that area. diff --git a/elpa/auctex-13.1.3/doc/preview-todo.texi b/elpa/auctex-13.1.3/doc/preview-todo.texi new file mode 100644 index 0000000..485373e --- /dev/null +++ b/elpa/auctex-13.1.3/doc/preview-todo.texi @@ -0,0 +1,118 @@ +@ifset rawfile +@include macros.texi +@chapheading Future Development of @previewlatex{} +@end ifset + +@itemize @bullet + +@item Support other formats than just @LaTeX{} + +plain @TeX{} users and @ConTeXt{} users should not have to feel left +out. While @ConTeXt{} is not supported yet by released versions of +@AUCTeX{}, at least supporting plain would help people, and be a start +for @ConTeXt{} as well. There are plain-based formats like MusiX@TeX{} +that could benefit a lot from @previewlatex{}. The main part of the +difficulties here is to adapt @file{preview.dtx} to produce stuff not +requiring @LaTeX{}. + +@item Support nested snippets + +Currently you can't have both a footnote (which gets displayed as just +its footnote number) and math inside of a footnote rendered as an image: +such nesting might be achieved by rerunning @previewlatex{} on the +footnote contents when one opens the footnote for editing. + +@item Support other text properties than just images + +Macros like @samp{\textit} can be rendered as images, but the resulting +humungous blob is not suitable for editing, in particular since the +line filling from LaTeX does not coincide with that of Emacs. It would +be much more useful if text properties just switched the relevant font +to italics rather than replacing the whole text with an image. It +would also make editing quite easier. Then there are things like +footnotes that are currently just replaced by their footnote number. +While editing is not a concern here (the number is not in the original +text, anyway), it would save a lot of conversion time if no images were +generated, but Emacs just displayed a properly fontified version of the +footnote number. Also, this might make @previewlatex{} useful even on +text terminals. + +@item Find a way to facilitate Source Specials + +Probably in connection with adding appropriate support to +@code{dvipng}, it would be nice if clicking on an image from a larger +piece of source code would place the cursor at the respective source +code location. + +@item Make @file{preview.dtx} look reasonable in @AUCTeX{} + +It is a bit embarrassing that @file{preview.dtx} is written in a manner +that will not give either good syntax highlighting or good indentation +when employing @AUCTeX{}. + +@item Web page work + +Currently, @previewlatex{}'s web page is not structured at all. Better +navigation would be desirable, as well as separate News and Errata eye +catchers. + +@item Manual improvements + +@itemize @minus +@item Pepper the manual with screen shots and graphics + +This will be of interest for the @acronym{HTML} and @TeX{} renditions +of the texinfo manual. Since Texinfo now supports images as well, this +could well be nice to have. + +@item Fix duplicates + +Various stuff appears several times. + +@end itemize + +@item Implement rendering pipelines for Emacs + +The current @previewlatex{} interface is fundamentally flawed, not only +because of a broken implementation. A general batchable and +daemonizable rendering infrastructure that can work on all kinds of +preview images for embedding into buffers is warranted. The current +implementation has a rather adhoc flavor and is not easily extended. +It will not work outside of @AUCTeX{}, either. + +@item Integrate into Ref@TeX{} + +When referencing to equations and the like, the preview-images of the +source rather than plain text should be displayed. If the preview in +question covers labels, those should appear in the bubble help and/or a +context menu. Apropos: + +@item Implement @LaTeX{} error indicators + +Previews on erroneous @LaTeX{} passages might gain a red border or similar. + +@item Pop up relevant online documentation for frequent errors + +A lot of errors are of the ``badly configured'' variety. Perhaps the +relevant info pages should be delivered in addition to the error +message. + +@item Implement a table editing mode where every table cell gets output +as a separate preview. Alternatively, output the complete table +metrics in a way that lets people click on individual cells for editing +purposes. + +@item Benchmark and kill Emacs inefficiencies + +Both the @LaTeX{} run under Emacs control as well as actual image +insertion in Emacs could be faster. CVS Emacs has improved in that +respect, but it still is slower than desirable. + +@item Improve image support under Emacs + +The general image and color handling in Emacs is inefficient and partly +defective. This is still the case in CVS. One option would be to +replace the whole color and image handling with @acronym{GDK} routines +when this library is available, since it has been optimized for it. + +@end itemize diff --git a/elpa/auctex-13.1.3/doc/quickstart.texi b/elpa/auctex-13.1.3/doc/quickstart.texi new file mode 100644 index 0000000..9731d15 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/quickstart.texi @@ -0,0 +1,327 @@ +@include macros.texi + +@node Quick Start +@chapter Quick Start + +@AUCTeX{} is a powerful program offering many features and configuration +options. If you are new to @AUCTeX{} this might be deterrent. +Fortunately you do not have to learn everything at once. This Quick +Start Guide will give you the knowledge of the most important commands +and enable you to prepare your first @LaTeX{} document with @AUCTeX{} +after only a few minutes of reading. + +In this introduction, we assume that @AUCTeX{} is already installed on +your system. If this is not the case, you should read the file +@file{INSTALL} in the base directory of the unpacked distribution +tarball. These installation instructions are available in this manual +as well, @ref{Installation}. We also assume that you are familiar with +the way keystrokes are written in Emacs manuals. If not, have a look at +the Emacs Tutorial in the Help menu. + +If @AUCTeX{} is installed in any other way than from the Emacs package +manager (@acronym{ELPA}), you might still need to activate it, by +inserting + +@lisp +(load "auctex.el" nil t t) +@end lisp +@noindent +in your user init file.@footnote{This usually is a file in your home +directory called @file{.emacs}, or @file{.emacs.d/init.el}.} + +If @AUCTeX{} is installed from @acronym{ELPA}, the installation +procedure already cares about loading @AUCTeX{} correctly and you +@strong{must not} have the line above in your init file. Note that this +also applies if you have the following line in your init file + +@lisp +(package-initialize) +@end lisp + +In order to get support for many of the @LaTeX{} packages you will use +in your documents, you should enable document parsing as well, which can +be achieved by putting + +@lisp +(setq TeX-auto-save t) +(setq TeX-parse-self t) +@end lisp +@noindent +into your init file. Finally, if you often use @code{\include} or +@code{\input}, you should make @AUCTeX{} aware of the multifile +document structure. You can do this by inserting + +@lisp +(setq-default TeX-master nil) +@end lisp + +into your init file. Each time you open a new file, @AUCTeX{} will then +ask you for a master file. + +@menu +* Editing Facilities:: Functions for editing TeX files +* Processing Facilities:: Creating and viewing output, debugging +@end menu + +@iftex +This Quick Start Guide covers two main topics: First we explain how +@AUCTeX{} helps you in editing your input file for @TeX{}, @LaTeX{}, and +some other formats. Then we describe the functions that @AUCTeX{} +provides for processing the input files with @LaTeX{}, Bib@TeX{}, etc., +and for viewing and debugging. +@end iftex + +@node Editing Facilities +@section Functions for editing TeX files + +@subsection Making your @TeX{} code more readable + +@AUCTeX{} can do syntax highlighting of your source code, that means +commands will get special colors or fonts. This is enabled by default. +You can disable it locally by typing @kbd{M-x font-lock-mode @key{RET}}. + +@AUCTeX{} will indent new lines to indicate their syntactical +relationship to the surrounding text. For example, the text of a +@code{\footnote} or text inside of an environment will be indented +relative to the text around it. If the indenting has gotten wrong after +adding or deleting some characters, use @key{TAB} to reindent the line, +@kbd{M-q} for the whole paragraph, or @kbd{M-x LaTeX-fill-buffer @key{RET}} +for the whole buffer. + +@subsection Entering sectioning commands +@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} +commands may be eased by using @kbd{C-c C-s}. You will be asked for the +section level. As nearly everywhere in @AUCTeX{}, you can use the +@key{TAB} or @key{SPC} key to get a list of available level names, and +to auto-complete what you started typing. Next, you will be asked for +the printed title of the section, and last you will be asked for a label +to be associated with the section. + +@subsection Inserting environments + +Similarly, you can insert environments, that is +@samp{\begin@{@}}--@samp{\end@{@}} pairs: Type @kbd{C-c C-e}, and select +an environment type. Again, you can use @key{TAB} or @key{SPC} to get a +list, and to complete what you type. Actually, the list will not only +provide standard @LaTeX{} environments, but also take your +@samp{\documentclass} and @samp{\usepackage} commands into account if +you have parsing enabled by setting @code{TeX-parse-self} to @code{t}. +If you use a couple of environments frequently, you can use the @key{up} and +@key{down} arrow keys (or @kbd{M-p} and @kbd{M-n}) in the minibuffer to get +back to the previously inserted commands. + +Some environments need additional arguments. Often, @AUCTeX{} knows about +this and asks you to enter a value. + +@subsection Inserting macros + +@kbd{C-c C-m}, or simply @kbd{C-c RET} will give you a prompt that asks +you for a @LaTeX{} macro. You can use @key{TAB} for completion, or the +@key{up}/@key{down} arrow keys (or @kbd{M-p} and @kbd{M-n}) to browse the command +history. In many cases, @AUCTeX{} knows which arguments a macro needs +and will ask you for that. It even can differentiate between mandatory +and optional arguments---for details, see @ref{Completion}. + +An additional help for inserting macros is provided by the possibility +to complete macros right in the buffer. With point at the end of a +partially written macro, you can complete it by typing @kbd{M-@key{TAB}}. + +@subsection Changing the font + +@AUCTeX{} provides convenient keyboard shortcuts for inserting macros +which specify the font to be used for typesetting certain parts of the +text. They start with @kbd{C-c C-f}, and the last @kbd{C-} combination +tells @AUCTeX{} which font you want: + +@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-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-d +@kindex C-c C-f C-c +@cindex Deleting fonts +Delete the innermost font specification containing point. + +@end table + +If you want to change font attributes of existing text, mark it as an +active region, and then invoke the commands. If no region is selected, +the command will be inserted with empty braces, and you can start typing +the changed text. + +Most of those commands will also work in math mode, but then macros like +@code{\mathbf} will be inserted. + + +@subsection Other useful features + +@AUCTeX{} also tries to help you when inserting the right ``quote'' +signs for your language, dollar signs to typeset math, or pairs of +braces. It offers shortcuts for commenting out text (@kbd{C-c ;} for +the current region or @kbd{C-c %} for the paragraph you are in). The +same keystrokes will remove the % signs, if the region or paragraph is +commented out yet. With @code{TeX-fold-mode}, you can hide certain +parts (like footnotes, references etc.)@: that you do not edit currently. +Support for Emacs' outline mode is provided as well. And there's more, +but this is beyond the scope of this Quick Start Guide. + + + +@node Processing Facilities +@section Creating and viewing output, debugging + +@subsection One Command for @LaTeX{}, helpers, viewers, and printing + +If you have typed some text and want to run @LaTeX{} (or @TeX{}, or +other programs---see below) on it, type @kbd{C-c C-c}. If applicable, +you will be asked whether you want to save changes, and which program +you want to invoke. In many cases, the choice that @AUCTeX{} suggests +will be just what you want: first @command{latex}, then a viewer. If a +@command{latex} run produces or changes input files for +@command{makeindex}, the next suggestion will be to run that program, +and @AUCTeX{} knows that you need to run @command{latex} again +afterwards---the same holds for Bib@TeX{}. + +When no processor invocation is necessary anymore, @AUCTeX{} will +suggest to run a viewer, or you can chose to create a PostScript file +using @command{dvips}, or to directly print it. + +Actually, there is another command which comes in handy to compile +documents: type @kbd{C-c C-a} (@code{TeX-command-run-all}) and @AUCTeX{} +will compile the document for you until it is ready and then run the +viewer. This is the same as issuing repeatedly @kbd{C-c C-c} and +letting @AUCTeX{} guess the next command to run. + +At this place, a warning needs to be given: First, although @AUCTeX{} is +really good in detecting the standard situations when an additional +@command{latex} run is necessary, it cannot detect it always. Second, +the creation of PostScript files or direct printing currently only works +when your output file is a @acronym{DVI} file, not a @acronym{PDF} file. + +Ah, you didn't know you can do both? That brings us to the next topic. + +@subsection Choosing an output format + +From a @LaTeX{} file, you can produce @acronym{DVI} output, or a +@acronym{PDF} file directly @i{via} @command{pdflatex}. You can switch +on source specials for easier navigation in the output file, or tell +@command{latex} to stop after an error (usually @option{--noninteractive} +is used, to allow you to detect all errors in a single run). + +These options are controlled by toggles, the keystrokes should be easy +to memorize: + +@table @kbd +@item C-c C-t C-p +@kindex C-c C-t C-p +This command toggles between @acronym{DVI} and @acronym{PDF} output + +@item C-c C-t C-i +@kindex C-c C-t C-i +toggles interactive mode + +@item C-c C-t C-s +@kindex C-c C-t C-s +toggles Sync@TeX{} (or source specials) support + +@item C-c C-t C-o +@kindex C-c C-t C-o +toggles usage of Omega/lambda. + +@end table + +There is also another possibility: compile the document with +@command{tex} (or @command{latex}) and then convert the resulting +@acronym{DVI} file to @acronym{PDF} using +@command{dvips}--@command{ps2pdf} sequence or @command{dvipdfmx} command. +If you want to go by this route, customize @code{TeX-PDF-from-DVI} option. +Then @AUCTeX{} will suggest you to run the appropriate command when +you type @kbd{C-C C-c}. For details, see @ref{Processor Options}. + +@subsection Debugging @LaTeX{} + +When @AUCTeX{} runs a program, it creates an output buffer in which it +displays the output of the command. If there is a syntactical error in +your file, @command{latex} will not complete successfully. @AUCTeX{} +will tell you that, and you can get to the place where the first error +occured by pressing @kbd{C-c `} (the last character is a backtick). The +view will be split in two windows, the output will be displayed in the +lower buffer, and both buffers will be centered around the place where +the error ocurred. You can then try to fix it in the document buffer, +and use the same keystrokes to get to the next error. This procedure +may be repeated until all errors have been dealt with. By pressing +@kbd{C-c C-w} (@code{TeX-toggle-debug-boxes}) you can toggle whether +@AUCTeX{} should notify you of overfull and underfull boxes in addition +to regular errors. + +Issue @kbd{M-x TeX-error-overview @key{RET}} to see a nicely formatted list of +all errors and warnings reported by the compiler. + +If a command got stuck in a seemingly infinite loop, or you want to stop +execution for other reasons, you can use @kbd{C-c C-k} (for ``kill''). +Similar to @kbd{C-l}, which centers the buffer you are in around your +current position, @kbd{C-c C-l} centers the output buffer so that the +last lines added at the bottom become visible. + +@subsection Running @LaTeX{} on parts of your document + +If you want to check how some part of your text looks like, and do not +want to wait until the whole document has been typeset, then mark it as +a region and use @kbd{C-c C-r}. It behaves just like @kbd{C-c C-c}, but +it only uses the document preamble and the region you marked. + +If you are using @code{\include} or @code{\input} to structure your +document, try @kbd{C-c C-b} while you are editing one of the included +files. It will run @command{latex} only on the current buffer, using the +preamble from the master file. + +@c Local Variables: +@c mode: texinfo +@c TeX-master: "auctex" +@c End: diff --git a/elpa/auctex-13.1.3/doc/tex-ref.tex b/elpa/auctex-13.1.3/doc/tex-ref.tex new file mode 100644 index 0000000..a7dfa34 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/tex-ref.tex @@ -0,0 +1,683 @@ +% Reference Card for AUCTeX version 13.1 +%**start of header +\newcount\columnsperpage + +% This file has only been checked with 3 columns per page. But it +% should print fine either via DVI or PDFTeX. + +\columnsperpage=3 + +% Papersize stuff. Use default paper size for PDF, but switch +% orientation. Use papersize special for dvips. + +\ifx\pdfoutput\undefined + \csname newcount\endcsname\pdfoutput + \pdfoutput=0 +\fi + +\ifnum\pdfoutput=0 +% \special{papersize 8.5in,11in}% + \special{papersize 297mm,210mm}% +\else + \dimen0\pdfpagewidth + \pdfpagewidth\pdfpageheight + \pdfpageheight\dimen0 +\fi + + +% This file is intended to be processed by plain TeX (TeX82). +% compile-command: "tex tex-ref" or "pdftex tex-ref" +% +% Original author of Auc-TeX Reference Card: +% +% Terrence Brannon, PO Box 5027, Bethlehem, PA 18015 , USA +% internet: tb06@pl118f.cc.lehigh.edu (215) 758-1720 (215) 758-2104 +% +% Kresten Krab Thorup updated the reference card to 6. +% Per Abrahamsen updated the reference card to 7, 8, and 9. +% Ralf Angeli updated it to 11.50. +% And David Kastrup messed around with it, too, merging the math reference. +% +% Thanks to Stephen Gildea +% Paul Rubin, Bob Chassell, Len Tower, and Richard Mlynarik +% for creating the GNU Emacs Reference Card from which this was mutated + +\def\versionnumber{13.1} +\def\year{2022} +\def\version{February \year\ v\versionnumber} + +\def\shortcopyrightnotice{\vskip 1ex plus 2 fill + \centerline{\small \copyright\ \year\ Free Software Foundation, Inc. + Permissions on back. v\versionnumber}} + +\def\copyrightnotice{% +\vskip 1ex plus 2 fill\begingroup\small +\centerline{Copyright \copyright\ 1987, 1992-1994, 2004-2006, 2008, 2010,} +\centerline{2012, 2014-2017, 2019-2022 Free Software Foundation, Inc.} +\centerline{for AUC\TeX\ version \versionnumber} + +Permission is granted to make and distribute copies of +this card provided the copyright notice and this permission notice +are preserved on all copies. + + +\endgroup} + +% make \bye not \outer so that the \def\bye in the \else clause below +% can be scanned without complaint. +\def\bye{\par\vfill\supereject\end} + +\newdimen\intercolumnskip +\newbox\columna +\newbox\columnb + +\edef\ncolumns{\the\columnsperpage} + +\message{[\ncolumns\space + column\if 1\ncolumns\else s\fi\space per page]} + +\def\scaledmag#1{ scaled \magstep #1} + +% This multi-way format was designed by Stephen Gildea +% October 1986. +\if 1\ncolumns + \hsize 4in + \vsize 10in + \voffset -.7in + \font\titlefont=\fontname\tenbf \scaledmag3 + \font\headingfont=\fontname\tenbf \scaledmag2 + \font\smallfont=\fontname\sevenrm + \font\smallsy=\fontname\sevensy + + \footline{\hss\folio} + \def\makefootline{\baselineskip10pt\hsize6.5in\line{\the\footline}} +\else + \hsize 3.2in + \vsize 7.6in + \hoffset -.75in + \voffset -.8in + \font\titlefont=cmbx10 \scaledmag2 + \font\headingfont=cmbx10 \scaledmag1 + \font\smallfont=cmr6 + \font\smallsy=cmsy6 + \font\eightrm=cmr8 + \font\eightbf=cmbx8 + \font\eightit=cmti8 + \font\eighttt=cmtt8 + \font\eightsl=cmsl8 + \font\eightsc=cmcsc8 + \font\eightsy=cmsy8 + \textfont0=\eightrm + \textfont2=\eightsy + \def\rm{\fam0 \eightrm} + \def\bf{\eightbf} + \def\it{\eightit} + \def\tt{\eighttt} + \def\sl{\eightsl} + \def\sc{\eightsc} + \normalbaselineskip=.8\normalbaselineskip + \ht\strutbox.8\ht\strutbox + \dp\strutbox.8\dp\strutbox + \normallineskip=.8\normallineskip + \normallineskiplimit=.8\normallineskiplimit + \normalbaselines\rm %make definitions take effect + + \if 2\ncolumns + \let\maxcolumn=b + \footline{\hss\rm\folio\hss} + \def\makefootline{\vskip 2in \hsize=6.86in\line{\the\footline}} + \else \if 3\ncolumns + \let\maxcolumn=c + \nopagenumbers + \else + \errhelp{You must set \columnsperpage equal to 1, 2, or 3.} + \errmessage{Illegal number of columns per page} + \fi\fi + + \intercolumnskip=.46in + \def\abc{a} + \output={% + % This next line is useful when designing the layout. + %\immediate\write16{Column \folio\abc\space starts with \firstmark} + \if \maxcolumn\abc \multicolumnformat \global\def\abc{a} + \else\if a\abc + \global\setbox\columna\columnbox \global\def\abc{b} + %% in case we never use \columnb (two-column mode) + \global\setbox\columnb\hbox to -\intercolumnskip{} + \else + \global\setbox\columnb\columnbox \global\def\abc{c}\fi\fi} + \def\multicolumnformat{\shipout\vbox{\makeheadline + \hbox{\box\columna\hskip\intercolumnskip + \box\columnb\hskip\intercolumnskip\columnbox} + \makefootline}\advancepageno} + \def\columnbox{\leftline{\pagebody}} + + \def\bye{\par\vfill\supereject + \if a\abc \else\null\vfill\eject\fi + \if a\abc \else\null\vfill\eject\fi + \end} +\fi + +% we won't be using math mode much, so redefine some of the characters +% we might want to talk about +\catcode`\^=12 +\catcode`\_=12 + +\chardef\\=`\\ +\chardef\{=`\{ +\chardef\}=`\} + +\hyphenation{mini-buf-fer} + +\parindent 0pt +\parskip 1ex plus .5ex minus .5ex + +\def\small{\smallfont\textfont2=\smallsy\baselineskip=.8\baselineskip} + +\def\newcolumn{\vfill\eject} + +\def\title#1{{\titlefont\centerline{#1}}\vskip 1ex plus .5ex} + +\def\section#1{\par\vskip 0pt plus 0.2\vsize \penalty-3000 + \vskip 0pt plus -0.2\vsize + \vskip 3ex plus 2ex minus 2ex {\headingfont #1}\mark{#1}% + \vskip 2ex plus 1ex minus 1.5ex} + +\newdimen\keyindent + +\def\beginindentedkeys{\keyindent=1em} +\def\endindentedkeys{\keyindent=0em} +\endindentedkeys + +\def\paralign{\vskip\parskip\halign} + +\def\<#1>{$\langle${\rm #1}$\rangle$} + +\def\kbd#1{{\tt#1}\null} %\null so not an abbrev even if period follows +\def\var#1{{\tt #1}} +\def\file#1{{\tt #1}} + +\def\beginexample{\par\leavevmode\begingroup + \obeylines\obeyspaces\parskip0pt\tt} +{\obeyspaces\global\let =\ } +\def\endexample{\endgroup} + +\def\key#1#2{\leavevmode\hbox to \hsize{\vtop + {\hsize=.68\hsize\rightskip=1em + \hskip\keyindent\relax#1}\kbd{#2}\hfil}} + +\newbox\metaxbox +\setbox\metaxbox\hbox{\kbd{M-x }} +\newdimen\metaxwidth +\metaxwidth=\wd\metaxbox + +\def\metax#1#2{\leavevmode\hbox to \hsize{\hbox to .75\hsize + {\hskip\keyindent\relax#1\hfil}% + \hskip -\metaxwidth minus 1fil + \kbd{#2}\hfil}} + +\def\threecol#1#2#3{\hskip\keyindent\relax#1\hfil&\kbd{#2}\quad + &\kbd{#3}\quad\cr} + +\def\LaTeX{% + L\kern-.36em\raise.3ex\hbox{\sc{a}}\kern-.15em\TeX} + +%**end of header + +\title{AUC\TeX\ Reference Card} + +\centerline{(for version \versionnumber)} + +\section{Conventions Used} + +\key{Carriage Return or \kbd{C-m}}{RET} +\key{Tabular or \kbd{C-i}}{TAB} +\key{Linefeed or \kbd{C-j}}{LFD} + +\section{Shell Interaction} + +\key{Run a command on the master file}{C-c C-c} +\key{Run a command on the buffer}{C-c C-b} +\key{Run a command on the region}{C-c C-r} +\key{Fix the region}{C-c C-t C-r} +\key{Kill job}{C-c C-k} +\key{Recenter output buffer}{C-c C-l} +\key{Next error in \TeX/\LaTeX\ session}{C-c `} +\key{Previous error in \TeX/\LaTeX\ session}{M-g p} +\key{Toggle debug of bad boxes}{C-c C-t C-b} +\key{Toggle debug of warnings}{C-c C-t C-w} +\key{View output file}{C-c C-v} +\key{Compile all and view output file}{C-c C-a} + +Commands you can run on the master file (with \kbd{C-c C-c}) or the +region (with \kbd{C-c C-r}) include the following (starred versions +are not available in all modes): + +\def\star{\llap{\rm*}} +\key{\TeX}{\star TeX} +\key{\LaTeX}{\star LaTeX} +\key{Con\TeX{}t (once)}{\star ConTeXt} +\key{Con\TeX{}t Full}{\star ConTeXt Full} +\key{Makeinfo}{\star Makeinfo} +\key{Makeinfo with HTML output}{\star Makeinfo HTML} +\key{Appropriate previewer}{View} +\key{Print the output}{Print} +\key{Bib\TeX}{BibTeX} +\key{Biber}{Biber} +\key{MakeIndex}{Index} +\key{LaCheck}{Check} +\key{Make (PostScript) File}{File} +\key{Ispell}{Spell} +\key{Delete intermediate files}{Clean} +\key{Delete all output files}{Clean All} + +\section{\TeX ing options} +\TeX\ runs can come in various types, which may be toggled and are +indicated in the mode line. + +\key{PDF/DVI mode}{C-c C-t C-p} +\key{Stop on errors (Interactive mode)}{C-c C-t C-i} +\key{I/O correlation (S. Specials, Sync\TeX)}{C-c C-t C-s} + +\section{Miscellaneous} + +\key{Read AUC\TeX\ manual}{C-c TAB} +\key{Find documentation}{C-c ?} +\key{Math Mode}{C-c \string~} +\key{Reset Buffer}{C-c C-n} +\key{Reset AUC\TeX}{C-u C-c C-n} + +\section{Multifile Handling} + +\key{Save Document}{C-c C-d} +\key{Switch to master file or active buffer}{C-c ^} +\key{Query for a master file}{C-c \_} + +\section{Command Insertion} + +\key{Insert Section}{C-c C-s} +\key{Insert \LaTeX\ environment}{C-c C-e} +\key{Insert item}{C-c LFD} +\key{Insert item (alias)}{M-RET} +\key{Close \LaTeX\ environment}{C-c ]} +\key{Insert \TeX\ macro \kbd{\{\}} }{C-c C-m} +\key{Insert double brace}{C-c \{} +\key{Complete \TeX\ macro}{M-TAB} +\key{Smart ``quote''}{"} +\key{Smart ``dollar''}{\$} + +\section{Font Selection} + +\key{Insert {\bf bold\/} text}{C-c C-f C-b} +\key{Insert {\it italics\/} text}{C-c C-f C-i} +\key{Insert {\rm roman} text}{C-c C-f C-r} +\key{Insert {\it emphasized\/} text}{C-c C-f C-e} +\key{Insert {\tt typewriter\/} text}{C-c C-f C-t} +\key{Insert {\sl slanted\/} text}{C-c C-f C-s} +\key{Insert {\sc Small Caps\/} text}{C-c C-f C-c} +\key{Delete font}{C-c C-f C-d} +\key{Replace font}{C-u C-c C-f \<key>} + +\section{Source Formatting} + +\key{Indent current line}{TAB} +\key{Indent next line}{LFD} + +\key{Format a paragraph}{M-q} +\key{Format a region}{C-c C-q C-r} +\key{Format a section}{C-c C-q C-s} +\key{Format an environment}{C-c C-q C-e} + +\key{Mark an environment}{C-c .} +\key{Mark a section}{C-c *} + +\key{Comment or uncomment region}{C-c ;} +\key{Comment or uncomment paragraph}{C-c \%} + +\copyrightnotice + +\newcolumn + +\title{Math Mode} + +\section{Variables} + +All math mode commands are under the prefix key specified by +\var{LaTeX-math-abbrev-prefix}, default is ``\kbd{`}''. + +You can define your own math mode commands by setting the variable +\var{LaTeX-math-list} before enabling \var{LaTeX-math-mode}. + +\section{Greek Letters} + +\def\disp#1{\hbox to 6ex{$#1$\hfill}} +\def\twocol#1\par{{% + \def\key##1##2{##1&##2\cr}% + \setbox0\vbox{\halign to 0.45\hsize{\tabskip0ptplus1fil\relax + ##\hfil&\kbd{##}\hfil\cr\vrule width0ptheight\ht\strutbox#1}}% + \line{% + \splittopskip=\ht\strutbox + \dimen0\ht0 + \advance\dimen0\baselineskip + \setbox2\vsplit0to0.5\dimen0 + \vtop{\unvbox2}\hfill\raise \ht\strutbox \vtop {\unvbox0}}}} +\def\keycs#1#2#{\keycsii#1{#2}} +\def\keycsii#1#2#3{\key{\disp{#1#2} ({\tt\string#1})}{#3}} + +\twocol +\keycs\alpha{a} +\keycs\beta{b} +\keycs\gamma{g} +\keycs\delta{d} +\keycs\epsilon{e} +\keycs\zeta{z} +\keycs\eta{h} +\keycs\theta{j} +\keycs\kappa{k} +\keycs\lambda{l} +\keycs\mu{m} +\keycs\nu{n} +\keycs\xi{x} +\keycs\pi{p} +\keycs\rho{r} +\keycs\sigma{s} +\keycs\tau{t} +\keycs\upsilon{u} +\keycs\phi{f} +\keycs\chi{q} +\keycs\psi{y} +\keycs\omega{w} +\keycs\Delta{D} +\keycs\Gamma{G} +\keycs\Theta{J} +\keycs\Lambda{L} +\keycs\Xi{X} +\keycs\Pi{P} +\keycs\Sigma{S} +\keycs\Upsilon{U} +\keycs\Phi{F} +\keycs\Psi{Y} +\keycs\Omega{W} + +\section{Symbols} + +\twocol +\keycs\rightarrow{C-f} +\keycs\leftarrow{C-b} +\keycs\uparrow{C-p} +\keycs\downarrow{C-n} +\keycs\leq{<} +\keycs\geq{>} +\keycs\tilde x{\string~} +\keycs\hat x{^} +\keycs\nabla{N} +\keycs\infty{I} +\keycs\forall{A} +\keycs\exists{E} +\keycs\not \ {/} +\keycs\in{i} +\keycs\times{*} +\keycs\cdot{.} +\keycs\colon{:} +\keycs\subset{\{} +\keycs\supset{\}} +\keycs\subseteq{[} +\keycs\supseteq{]} +\keycs\emptyset{0} +\keycs\setminus{\\} +\keycs\cup{+} +\keycs\cap{-} +\keycs\langle{(} +\keycs\rangle{)} +\keycs\exp{C-e} +\keycs\sin{C-s} +\keycs\cos{C-c} +\keycs\sup{C-^} +\keycs\inf{C-_} +\keycs\det{C-d} +\keycs\lim{C-l} +\keycs\tan{C-t} +\keycs\vee{|} +\keycs\wedge{\&} + +\section{Miscellaneous} + +\key{cal letters}{c \<letter>} + +\newcolumn + +\def\previewlatex{{preview-latex}} +\title{\previewlatex} +\section{Activation} +\previewlatex\ is part of AUC\TeX. If it is active, you should see an +entry ``Preview'' in the menu bar when editing \LaTeX{} files. If you +have a ``LaTeX'', but no ``Preview'' menu, add the following to your +init file (usually \file{\string~/.emacs.d/init.el}): +\beginexample +(load "preview-latex.el" nil t t) +\endexample + +\section{Usage and keybindings} +\previewlatex\ operation only affects the display of the buffer, not +its contents. It runs only on demand, using the target {\sc dvi} or +{\sc PDF} files in the process. The first command in the following +list (also on the toolbar button) will (as applicable) repreview an +active region or a single modified preview, toggle the visibility of +an unmodified preview or generate previews for a surrounding buffer +area up to the next preview. + +\key{Preview at point}{C-c C-p C-p} +\key{Preview environment}{C-c C-p C-e} +\key{Preview region}{C-c C-p C-r} +\key{Preview buffer}{C-c C-p C-b} +\key{Preview document}{C-c C-p C-d} +\key{Remove previews at point}{C-c C-p C-c C-p} +\key{Remove previews from region}{C-c C-p C-c C-r} +\key{Remove previews from buffer}{C-c C-p C-c C-b} +\key{Remove previews from document}{C-c C-p C-c C-d} +\key{Cache preamble}{C-c C-p C-f} +\key{Switch off preamble cache}{C-c C-p C-c C-f} +\key{Read Texinfo manual}{C-c C-p TAB} +\key{Copy region as MML}{C-c C-p C-w} + +The last keysequence will copy a region with previews into the kill +ring in a form fit for sending in Emacs' {\tt message-mode}. + +\section{Customization within Emacs} + +You can use \kbd{M-x customize-variable RET} or the ``Preview\slash +Customize'' menu for customization. Worthwhile settings: + +\halign to \hsize{\tabskip=1ptplus1fil\relax#\hfil&\hfil\var{#}\tabskip0pt\cr +\noalign{\medskip If you have dvipng available:} +Set to \kbd{dvipng}&preview-image-type\cr +\noalign{\medskip \vbox{Keep counter values when regenerating + single previews:}} +Set to \kbd{t}&preview-preserve-counters\cr +\noalign{\medskip \vbox{Cache/Don't cache preamble without query +(preamble caching is done using \file{mylatex.ltx} and might not always +work. Use the appropriate key sequences for overriding the following +setting):}} +Set to \kbd{t}/\kbd{nil}&preview-auto-cache-preamble\cr} + +\section{Customization from \LaTeX{}} +Customization is done in the document preamble (you need to load +\file{preview.sty} explicitly) or in \file{prauctex.cfg} (which should +load the system \file{prauctex.cfg} first). Commands: + +\halign to \hsize{\tabskip=1ptplus1fil\relax#\hfil&\hfil\kbd{#}\tabskip0pt\cr +Preview macro&\string\PreviewMacro[\{\<args>\}]\{\<macro>\}\cr +Preview env&\string\PreviewEnvironment[\{\<args>\}]\{\<env>\}\cr +Skip macro&\string\PreviewMacro*[\{\<args>\}]\{\<macro>\}\cr +Skip env&\string\PreviewEnvironment*[\{\<args>\}]\{\<env>\}\cr +\noalign{\smallskip Diverting material from float environments} +Snarf stuff&\string\PreviewSnarfEnvironment[\{\<args>\}]\{\<env>\}\cr +} + +Values to be used within \<args>: +\halign to +\hsize{\tabskip=1ptplus1fil\relax#\hfil&\hfil\kbd{#}\tabskip0pt\cr +Optional argument&[]\cr +Mandatory argument&\{\}\cr +Optional star&*\cr +Conditionals&?\<token>\{\<if found>\}\{\<if not found>\}\cr +Skip next token&-\cr +Transformation&\#\{\<macro args>\}\{\<replacement>\}\cr +} + +More options and explanations can be found in \file{preview.pdf} or the +Texinfo manual. + +\vskip 5ex plus 6ex minus 1ex + +\title{Folding Source Display} + +\key{Toggle folding mode}{C-c C-o C-f} +\key{Hide all items in buffer}{C-c C-o C-b} +\key{Hide all items in region}{C-c C-o C-r} +\key{Hide all items in paragraph}{C-c C-o C-p} +\key{Hide current macro}{C-c C-o C-m} +\key{Hide current environment}{C-c C-o C-e} +\key{Show all items in buffer}{C-c C-o b} +\key{Show all items in region}{C-c C-o r} +\key{Show all items in paragraph}{C-c C-o p} +\key{Show current item}{C-c C-o i} +\key{Hide or show current item}{C-c C-o C-o} + +\vskip 5ex plus 6ex minus 1ex + +\title{Outlining \TeX\ Documents} + +AUC\TeX\ supports outline mode by defining section, subsection, +etc. as heading levels. You can use \kbd{M-x outline-minor-mode RET} +to toggle outline minor mode. All outline minor mode commands are +under the prefix key specified by \var{outline-minor-mode-prefix}, default +is \kbd{C-c @}. + +\key{Hide all of buffer except headings}{C-c @ C-t} +\key{Show all text in buffer}{C-c @ C-a} +\key{Hide body following this heading}{C-c @ C-c} +\key{Show body following this heading}{C-c @ C-e} +\key{Hide subtree}{C-c @ C-d} +\key{Show subtree}{C-c @ C-s} +\key{All subheadings visible}{C-c @ C-k} + +\key{next visible heading}{C-c @ C-n} +\key{previous visible heading}{C-c @ C-p} +\key{forward to next subheading}{C-c @ C-f} +\key{backward to next subheading}{C-c @ C-b} +\key{up one heading level}{C-c @ C-u} + +\newcolumn + +\iftrue % RefTeX long version + +\title{RefTeX} + +\section{Activation} + +RefTeX is part of Emacs. To activate and make it interact with +AUCTeX, insert the following lines in \file{init.el}. +\vskip-3mm +\beginexample +(add-hook 'LaTeX-mode-hook \#'turn-on-reftex) +(setq reftex-plug-into-AUCTeX t) +\endexample + +\section{Table of Contents} +The table of contents is a structured view of the entire document. It +contains the sections, and optionally labels, index entries, and file +boundaries. + +\key{Show the table of contents$\sp1$}{C-c =} +\key{Recenter *toc* buffer to here$\sp1$}{C-c -} + +\section{Crossreferences, Citations, Index} + +\key{Insert unique label$\sp1$}{C-c (} +\key{Reference a label$\sp1$}{C-c )} +\key{Insert citation with key selection}{C-c [} +\key{\dots\ prompt for optional arguments}{C-u C-c [} +\key{Index word at point with default macro}{C-c /} +\key{Insert an index entry}{C-c <} +\key{Add word to index phrases}{C-c \\} +\key{Visit index phrases buffer}{C-c |} +\key{Compile and display index}{C-c >} +\key{View cross reference$\sp1$}{C-c \&} +\key{View cross reference with mouse}{S-mouse-2} +\key{View cross reference from BibTeX file}{C-c \&} + +\section{Standard keys in special buffers} +RefTeX's special buffers have many active keys. The common ones are: + +\key{Display summary of active keys}{?} +\key{Select this item}{RET} +\key{Rescan the document}{r} +\key{Display location in other window}{SPC} +\key{Follow mode}{f} + +\section{Multifile actions} +Since RefTeX scans the entire (multifile) document, it can provide +commands that act on all files of a document. Check the \kbd{ +Ref->Global Actions} menu for these commands. + +\section{Variables} + +To tell reftex about your own macro definitions, customize the +variables +\vskip-3mm +\beginexample +reftex-label-alist +reftex-section-levels +reftex-index-macros +reftex-cite-format +\endexample + +\vskip2mm\hrule +$\sp1$ An argument of \kbd{C-u} triggers a document scan first. This can +be necessary if file content and RefTeX's knowledge are no longer +consistent. + +\else % RefTeX compact version + +\csname title\endcsname{RefTeX} + +\section{Activation in init.el} + +\vskip-4mm +\beginexample +(add-hook 'LaTeX-mode-hook \#'turn-on-reftex) +(setq reftex-plug-into-AUCTeX t) +\endexample + +\section{Table of Contents} + +\key{Show the table of contents$\sp1$}{C-c =} +\key{Recenter *toc* buffer to here$\sp1$}{C-c -} + +\section{Crossreferences, Citations, Index} + +\key{Insert unique label$\sp1$}{C-c (} +\key{Reference a label$\sp1$}{C-c )} +\key{Insert citation with key selection}{C-c [} +\key{... prompt for optional arguments}{C-u C-c [} +\key{Index word at point with default macro}{C-c /} +\key{Insert an index entry}{C-c <} +\key{Add word to index phrases}{C-c \\} +\key{Visit index phrases buffer}{C-c |} +\key{Compile and display index}{C-c >} +\key{View cross reference$\sp1$}{C-c \&} +\key{View cross reference with mouse}{S-mouse-2} +\key{View cross reference from BibTeX file}{C-c \&} + +\vskip2mm\hrule +$\sp1$ An argument of \kbd{C-u} triggers a document scan first. + +\fi + +\bye + +%%% Local Variables: +%%% mode: plain-TeX +%%% TeX-master: t +%%% End: diff --git a/elpa/auctex-13.1.3/doc/todo.texi b/elpa/auctex-13.1.3/doc/todo.texi new file mode 100644 index 0000000..218231d --- /dev/null +++ b/elpa/auctex-13.1.3/doc/todo.texi @@ -0,0 +1,311 @@ +@c This is part of the AUCTeX Manual. +@c Copyright (C) 2004-2006, 2008, 2009, 2013-2015, +@c 2020-2022 Free Software Foundation, Inc. +@c See the file auctex.texi for copying conditions. +@ifset rawfile +@include macros.texi +@node Development,,(dir),(dir) +@top Future Development of @AUCTeX{} +@end ifset + +The following sections describe future development of @AUCTeX{}. +Besides mid-term goals, bug reports and requests we cannot fix or honor +right away are being gathered here. If you have some time for Emacs +Lisp hacking, you are encouraged to try to provide a solution to one of +the following problems. If you don't know Lisp, you may help us to +improve the documentation. It might be a good idea to discuss proposed +changes on the mailing list of @AUCTeX{} first. + +@menu +* Mid-term Goals:: +* Wishlist:: +* Bugs:: +@end menu + +@ifset rawfile +@node Mid-term Goals +@chapter Mid-term Goals +@raisesections +@end ifset + +@ifclear rawfile +@node Mid-term Goals +@section Mid-term Goals +@end ifclear + +@itemize @bullet +@item Integration of @previewlatex{} into @AUCTeX{} + +As of @AUCTeX{} 11.81 @previewlatex{} is a part of @AUCTeX{} in the +sense that the installation routines were merged and @previewlatex{} is +being packaged with @AUCTeX{}. + +Further integration will happen at the backend. This involves folding +of error parsing and task management of both packages which will ease +development efforts and avoid redundant work. + +@item Error help catalogs + +Currently, the help for errors is more or less hardwired into +@file{latex.el}. For supporting error help in other languages, it would +be sensible to instead arrange error messages in language-specific +files, make a common info file from all such catalogs in a given +language and look the error texts up in an appropriate index. The user +would then specify a preference list of languages, and the errors would +be looked up in the catalogs in sequence until they were identified. + +@item Combining @samp{docTeX} with Ref@TeX{} + +Macro cross references should also be usable for document navigation +using Ref@TeX{}. + +@item Fix remove-style feature + +Currently @code{TeX-remove-style} implementation isn't good. It is common +practice that major mode functions directly add macros and environments +via @code{TeX-add-symbols} and @code{LaTeX-add-environments}, but those +macros and environments are lost once @code{TeX-remove-style} runs. It is +necessary to run major mode function, by e.g.@: @code{normal-mode}, again +to recover them, but that makes no point in running +@code{TeX-remove-style} itself because major mode function kills all +buffer-local variables. + +As of @AUCTeX{} 12.3, @code{TeX-remove-style} is no longer used by any +other codes. + +@item +Document @code{LaTeX-insert-into-commments}, +@code{TeX-translate-location-hook}, and usage of @ConTeXt{} mode. +@end itemize + +@node Wishlist +@section Wishlist + +@itemize @bullet +@item +Simplify tool bar implementation. The library @file{toolbar-x.el} was +developed as an abstraction layer to absorb difference between XEmacs +and @acronym{GNU} Emacs. Now that XEmacs is no longer supported, the +library, together with @file{tex-bar.el} as a whole, can be much +simplified (or even unified). + +@item Documentation lookup for macros + +A parser could gather information about which macros are defined in +which @LaTeX{} packages and store the information in a hashtable which +can be used in a backend for @code{TeX-doc} in order to open the +matching documentation for a given macro. The information could also be +used to insert an appropriate @samp{\usepackage} statement if the user +tries to insert a macro for which the respective package has not been +requested yet. + +@item Improvements to error reporting + +Fringe indicators for errors in the main text would be nice. + +@item A math entry grid + +A separate frame with a table of math character graphics to click on in +order to insert the respective sequence into the buffer (cf. the +``grid'' of @samp{x-symbol}). + +@item Crossreferencing support + +It would be nice if you could index process your favorite collection of +@file{.dtx} files (such as the @LaTeX{} source), just call a command on +arbitrary control sequence, and get either the @acronym{DVI} viewer opened right +at the definition of that macro (using Source Specials), or the source +code of the @file{.dtx} file. + +@item Better plain @TeX{} support + +For starters, @code{LaTeX-math-mode} is not very @LaTeX{}-specific in +the first place, and similar holds for indentation and formatting. + +@item +Page count when compiling should (optionally) go to modeline of the +window where the compilation command was invoked, instead of the output +window. Suggested by Karsten Tinnefeld +@email{tinnefeld@@irb.informatik.uni-dortmund.de}. + +@item +Command to insert a macrodefinition in the preamble, without moving +point from the current location. Suggested by +"Jeffrey C. Ely" @email{ely@@nwu.edu}. + +@item +A database of all commands defined in all stylefiles. When a command or +environment gets entered that is provided in one of the styles, insert +the appropriate @code{\usepackage} in the preamble. + +@item +A way to add and overwrite math mode entries in style files, and to +decide where they should be. Suggested by Remo Badii @email{Remo.Badii@@psi.ch}. + +@item +Create template for (first) line of tabular environment. + +@item +@c FIXME: Already fixed? +I think prompting for the master is the intended behaviour. It +corresponds to a `shared' value for @code{TeX-master}. + +There should probably be a `none' value which wouldn't query for the +master, but instead disable all features that relies on @code{TeX-master}. + +This default value for @code{TeX-master} could then be controled with mapping +based on the extension. + +@item +Use index files (when available) to speed up @kbd{C-c C-m include +@key{RET}}. + +@item +Option not to calculate very slow completions like for +@kbd{C-c C-m include @key{RET}}. + +@item +Font menu should be created from @code{TeX-font-list}. + +@item +Installation procedure written purely in emacs lisp. + +@item +Included PostScript files should also be counted as part of the +document. + +@item +A nice hierarchical by-topic organization of all officially documented +@LaTeX{} macros, available from the menu bar. + +@item +@code{TeX-command-default} should be set from the master file, if not +set locally. Suggested by Peter Whaite @email{peta@@cim.mcgill.ca}. + +@item +Make @AUCTeX{} work with @samp{crypt++}. Suggested by Chris Moore +@email{Chris.Moore@@src.bae.co.uk}. + +@item +Make @AUCTeX{} work with @samp{longlines}. This would also apply to +@previewlatex{}, though it might make sense to unify error processing +before attempting this. + +@item +@c FIXME: Already achieved? +The @samp{Spell} command should apply to all files in a document. Maybe +it could try to restrict to files that have been modified since last +spell check? Suggested by Ravinder Bhumbla @email{rbhumbla@@ucsd.edu}. + +@item +Make @key{.} check for abbreviations and sentences ending with capital +letters. + +@item +Use Emacs 19 minibuffer history to choose between previewers, and other +stuff. Suggested by John Interrante +@email{interran@@uluru.Stanford.EDU}. + +@item +Documentation of variables that can be set in a style hook. + +We need a list of what can safely be done in an ordinary style hook. +You can not set a variable that @AUCTeX{} depends on, unless @AUCTeX{} +knows that it has to run the style hooks first. + +Here is the start of such a list. +@table @code + +@item LaTeX-add-environments + +@item TeX-add-symbols + +@item LaTeX-add-labels + +@item LaTeX-add-bibliographies + +@item LaTeX-largest-level + +@end table + +@item +Outline should be (better) supported in @TeX{} mode. + +At least, support headers, trailers, as well as @code{TeX-outline-extra}. + +@item +@code{TeX-header-start} and @code{TeX-trailer-end}. + +We might want these, just for fun (and outlines) + +@item +Plain @TeX{} and @LaTeX{} specific header and trailer expressions. + +We should have a way to globally specify the default value of the header +and trailer regexps. + +@item +Get closer to original @code{TeX-mode} keybindings. + +A third initialization file (@file{tex-mode.el}) containing an emulator +of the standard @code{TeX-mode} would help convince some people to +change to @AUCTeX{}. + +@item +Use markers in @code{TeX-error-list} to remember buffer positions in +order to be more robust with regard to line numbers and changed files. + +@item +Finish the Texinfo mode. For one thing, many Texinfo mode commands do +not accept braces around their arguments. + +@item +Hook up the letter environment with @file{bbdb.el}. + +@end itemize + +@node Bugs +@section Bugs + +@c FIXME: Are those bugs still present? + +@itemize @bullet +@item +The style hooks automatically generated by parsing files for +@file{example.dtx}, @file{example.sty}, @file{example.drv} and +@file{example.bib} all clash. Bad. Clash with hand-written style hooks +should be removed by dialect discrimination --- to be checked. + +@item +@kbd{C-c `} should always stay in the current window, also when it finds +a new file. + +@item +Do not overwrite emacs warnings about existing auto-save files when +loading a new file. + +@item +Maybe the regexp for matching a @TeX{} symbol during parsing should be +@samp{"\\\\\\([a-zA-Z]+\\|.\\)"} --- +@email{thiemann@@informatik.uni-tuebingen.de} Peter Thiemann. + +@item +@AUCTeX{} should not parse verbatim environments. + +@item +Make @samp{`} check for math context in @code{LaTeX-math-mode}. and +simply self insert if not in a math context. + +@item +Make @code{TeX-insert-dollar} more robust. Currently it can be fooled +by @samp{\mbox}'es and escaped double dollar for example. + +@item +@c FIXME: Is support for table environment really necessary? +Correct indentation for tabbing, table, and math environments. +@end itemize + +@c Local Variables: +@c mode: texinfo +@c TeX-master: "auctex" +@c End: diff --git a/elpa/auctex-13.1.3/doc/wininstall.texi b/elpa/auctex-13.1.3/doc/wininstall.texi new file mode 100644 index 0000000..230f8e2 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/wininstall.texi @@ -0,0 +1,358 @@ +@c This is part of the AUCTeX Manual. +@c Copyright (C) 2003-2007, 2009, 2018, 2021 +@c Free Software Foundation, Inc. +@c See the file auctex.texi for copying conditions. +@ifset rawfile +@include macros.texi +@end ifset + +@subheading In a Nutshell + +The following are brief installation instructions for the impatient. In +case you don't understand some of this, run into trouble of some sort, +or need more elaborate information, refer to the detailed instructions +further below. + +@enumerate +@item +Install the prerequisites, i.e.@: GNU Emacs, MSYS or Cygwin, a @TeX{} +system, and Ghostscript. + +@item +Open the MSYS shell or a Cygwin shell and change to the directory +containing the unzipped file contents. + +@item +Configure @AUCTeX{}: + +For Emacs: Many people like to install @AUCTeX{} into the pseudo file +system hierarchy set up by the Emacs installation. Assuming Emacs is +installed in @file{C:/Program Files/Emacs} and the directory for local +additions of your @TeX{} system, e.g.@: MiK@TeX{}, is +@file{C:/localtexmf}, you can do this by typing the following statement +at the shell prompt: + +@example +./configure --prefix='C:/Program Files/Emacs' \ + --infodir='C:/Program Files/Emacs/info' \ + --with-texmf-dir='C:/localtexmf' +@end example + +The commands above is example for common usage. More on configuration +options can be found in the detailed installation instructions below. + +If the configuration script failed to find all required programs, make +sure that these programs are in your system path and add directories +containing the programs to the @env{PATH} environment variable if +necessary. Here is how to do that in W2000/XP: + +@enumerate +@cindex Adding to @env{PATH} in Windows +@cindex @env{PATH} in Windows +@item +On the desktop, right click ``My Computer'' and select properties. +@item +Click on ``Advanced'' in the ``System Properties'' window. +@item +Select ``Environment Variables''. +@item +Select ``path'' in ``System Variables'' and click ``edit''. Move to the +front in the line (this might require scrolling) and add the missing +path including drive letter, ended with a semicolon. +@end enumerate + +@item +If there were no further error messages, type + +@example +make +@end example + +In case there were, please refer to the detailed description below. + +@item +Finish the installation by typing + +@example +make install +@end example +@end enumerate + +@subheading Detailed Installation Instructions + +Installation of @AUCTeX{} under Windows is in itself not more +complicated than on other platforms. However, meeting the prerequisites +might require more work than on some other platforms, and feel less +natural. + +If you are experiencing any problems, even if you think they are of your +own making, be sure to report them to @email{auctex-devel@@gnu.org} so +that we can explain things better in future. + +Windows is a problematic platform for installation scripts. The main +problem is that the installation procedure requires consistent file +names in order to find its way in the directory hierarchy, and Windows +path names are a mess. + +The installation procedure tries finding stuff in system search paths +and in Emacs paths. For that to succeed, you have to use the same +syntax and spelling and case of paths everywhere: in your system search +paths, in Emacs' @code{load-path} variable, as argument to the scripts. +If your path names contain spaces or other `shell-unfriendly' +characters, most notably backslashes for directory separators, place the +whole path in @samp{"double quote marks"} whenever you specify it on a +command line. + +Avoid `helpful' magic file names like @samp{/cygdrive/c} and +@samp{C:\PROGRA~1\} like the plague. It is quite unlikely that the +scripts will be able to identify the actual file names involved. Use +the full paths, making use of normal Windows drive letters like +@samp{ 'C:/Program Files/Emacs' } where required, and using the same +combination of upper- and lowercase letters as in the actual files. +File names containing shell-special characters like spaces or +backslashes (if you prefer that syntax) need to get properly quoted to +the shell: the above example used single quotes for that. + +Ok, now here are the steps to perform: + +@enumerate +@item +You need to unpack the @AUCTeX{} distribution (which you seemingly have +done since you are reading this). It must be unpacked in a separate +installation directory outside of your Emacs file hierarchy: the +installation will later copy all necessary files to their final +destination, and you can ultimately remove the directory where you +unpacked the files. + +Line endings are a problem under Windows. The distribution contains +only text files, and theoretically most of the involved tools should get +along with that. However, the files are processed by various utilities, +and it is conceivable that not all of them will use the same line ending +conventions. If you encounter problems, it might help if you try +unpacking (or checking out) the files in binary mode, if your tools +allow that. + +If you don't have a suitable unpacking tool, skip to the next step: this +should provide you with a working @samp{unzip} command. + +@item +The installation of @AUCTeX{} will require the MSYS tool set from +@uref{http://www.mingw.org/} or the Cygwin tool set from +@uref{https://cygwin.com/}. The latter is slower and larger (the download +size of the base system is about 15 MB) but comes with a package manager +that allows for updating the tool set and installing additional packages +like, for example, the spell checker @w{aspell}. + +If Cygwin specific paths like @samp{/cygdrive/c} crop up in the course +of the installation, using a non-Cygwin Emacs could conceivably cause +trouble. Using Cygwin either for everything or nothing might save +headaches, @emph{if} things don't work out. + +@item +Install a current version of @w{Emacs} from +@uref{https://ftp.gnu.org/gnu/emacs/windows/}. + +@item +You need a working @TeX{} installation. One popular installation under +Windows is @uref{https://miktex.org/,MiK@TeX{}}. Another much more +extensive system is @uref{https://www.tug.org/texlive/,@w{@TeX{} Live}} +which is rather close to its Unix cousins. + +@item +A working copy of @uref{https://www.ghostscript.com/,Ghostscript} is +required for @previewlatex{} operation. Examining the output from +@example +gswin32c -h +@end example +on a Windows command line should tell you whether your Ghostscript +supports the @code{png16m} device needed for @acronym{PNG} support. +MiK@TeX{} apparently comes with its own Ghostscript called @file{mgs.exe}. + +@item +@uref{https://www.perl.org/,Perl} is needed for rebuilding the +documentation if you are working with a copy from Git or have +touched documentation source files in the @previewlatex{} part. If the +line endings of the file @file{preview/latex/preview.dtx} don't +correspond with what Perl calls @code{\n} when reading text files, +you'll run into trouble. + +@item +Now the fun stuff starts. If you have not yet done so, unpack the +@AUCTeX{} distribution into a separate directory after rereading the +instructions for unpacking above. + +@item +Ready for takeoff. Start some shell (typically @command{bash}) capable of +running @command{configure}, change into the installation directory and +call @command{./configure} with appropriate options. + +Typical options you'll want to specify will be +@table @code +@item --prefix=@var{drive:/path/to/emacs-hierarchy} +which tells @command{configure} where to perform the installation. It may +also make @command{configure} find Emacs automatically; if this doesn't +happen, try @option{--with-emacs} as described below. All automatic +detection of files and directories restricts itself to directories below +the @var{prefix} or in the same hierarchy as the program accessing the +files. Usually, directories like @file{man}, @file{share} and +@file{bin} will be situated right under @var{prefix}. + +This option also affects the defaults for placing the Texinfo +documentation files (see also @option{--infodir} below) and automatically +generated style hooks. + +If you have a central directory hierarchy (not untypical with Cygwin) +for such stuff, you might want to specify its root here. You stand a +good chance that this will be the only option you need to supply, as +long as your @TeX{}-related executables are in your system path, which +they better be for @AUCTeX{}'s operation, anyway. + +@item --with-emacs +if you are installing for a version of Emacs. You can use +@samp{--with-emacs=@var{drive:/path/to/emacs}} to specify the name of the +installed Emacs executable, complete with its path if necessary (if +Emacs is not within a directory specified in your @env{PATH} environment +setting). + +@item --with-lispdir=@var{drive:/path/to/site-lisp} +This option tells a place in @code{load-path} below which the +files are situated. The startup files @file{auctex.el} and +@file{preview-latex.el} will get installed here unless a subdirectory +@file{site-start.d} exists which will then be used instead. The other +files from @AUCTeX{} will be installed in a subdirectory called +@file{auctex}. + +If you think that you need a different setup, please refer to the full +installation instructions in +@ifset rawfile +the @file{INSTALL} file. +@end ifset +@ifclear rawfile +@ref{Configure}. +@end ifclear + +@item --infodir=@var{drive:/path/to/info/directory} +If you are installing into an Emacs directory, info files have to be put +into the @file{info} folder below that directory. The configuration +script will usually try to install into the folder @file{share/info}, so +you have to override this by specifying something like +@samp{--infodir='C:/Program Files/info'} for the configure call. + +@item --with-auto-dir=@var{drive:/dir} +Directory containing automatically generated information. You should +not normally need to set this, as @samp{--prefix} should take care of +this. + +@item --disable-preview +Use this option if your Emacs version is unable to support image +display. + +@item --with-texmf-dir=@var{drive:/dir} +This will specify the directory where your @TeX{} installation sits. If +your @TeX{} installation does not conform to the @acronym{TDS} (@TeX{} directory +standard), you may need to specify more options to get everything in +place. +@end table + +For more information about any of the above and additional options, see +@ifset rawfile +the `Configure' section in the @file{INSTALL} file. +@end ifset +@ifclear rawfile +@ref{Configure}. +@end ifclear + +@c FIXME: It seems this no longer holds. +@c Calling +@c @file{./configure --help=recursive} +@c will tell about other options, but those are almost never required. + +Some executables might not be found in your path. That is not a good +idea, but you can get around by specifying environment variables to +@command{configure}: +@example +GS="@var{drive:/path/to/gswin32c.exe}" ./configure @dots{} +@end example +should work for this purpose. @file{gswin32c.exe} is the usual name for +the required @emph{command line} executable under Windows; in contrast, +@file{gswin32.exe} is likely to fail. + +As an alternative to specifying variables for the @command{configure} call +you can add directories containing the required executables to the +@env{PATH} variable of your Windows system. This is especially a good +idea if Emacs has trouble finding the respective programs later during +normal operation. + +@item +Run @command{make} in the installation directory. + +@item +Run @code{make install} in the installation directory. + +@item +With Emacs, activation of @AUCTeX{} and @previewlatex{} depends on a +working @file{site-start.d} directory or similar setup, since then the +startup files @file{auctex.el} and @file{preview-latex.el} will have +been placed there. If this has not been done, you should be able to +load the startup files manually with +@lisp +(load "auctex.el" nil t t) +(load "preview-latex.el" nil t t) +@end lisp +in either a site-wide @file{site-start.el} or your personal startup file +(usually accessible as @file{~/.emacs} or @file{~/.emacs.d/init.el} from +within Emacs). + +@cindex @file{tex-mik.el} +The default configuration of @AUCTeX{} is probably not the best fit for +Windows systems with MiK@TeX{}. You might want to add +@lisp +(require 'tex-mik) +@end lisp +after loading @file{auctex.el} and @file{preview-latex.el} in order to +get more appropriate values for some customization options. + +You can always use + +@example +@kbd{M-x customize-group @key{RET} AUCTeX @key{RET}} +@end example + +in order to customize more stuff, or use the @samp{Customize} menu. + +@item +Load @file{circ.tex} into Emacs and see if you get the @samp{Command} +menu. Try using it to @LaTeX{} the file. + +@item +Check whether the @samp{Preview} menu is available in this file. Use it +to generate previews for the document. + +If this barfs and tells you that image type @samp{png} is not supported, +you can either add @acronym{PNG} support to your Emacs installation or +choose another image format to be used by @previewlatex{}. + +Adding support for an image format usually involves the installation of +a library, e.g.@: from @uref{http://gnuwin32.sf.net/}. If you got your +Emacs from @uref{https://www.gnu.org/} you might want to check its +@uref{https://ftp.gnu.org/gnu/emacs/windows/README,README file} for +details. + +A different image format can be chosen by setting the variable +@code{preview-image-type}. While it is recommended to keep the +@samp{dvipng} or @samp{png} setting, you can temporarily select a +different format like @samp{pnm} to check if the lack of @acronym{PNG} +support is the only problem with your Emacs installation. + +Try adding the line + +@lisp +(setq preview-image-type 'pnm) +@end lisp + +to your init file for a quick test. You should remove the line after +the test again, because @acronym{PNM} files take away @strong{vast} +amounts of disk space, and thus also of load/save time. +@end enumerate + +Well, that about is all. Have fun! |