AUC TeX
*******

AUC TeX is a fully integrated environment for editing LaTeX and TeX files.

This file documents AUC TeX version 7.3.

The keybindings have changed since 6.1, see Version 7.0 for details.

Although AUC TeX 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.  AUC TeX 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.

NOTE: This documentation is preliminary.  It should however cover most important points.  Corrections or perhaps rewrites of sections are VERY WELCOME.

Kresten Krab Thorup (6.0 original) Per Abrahamsen (later updates)

There is a mailing list for discussion about AUC TeX and announcement of alpha releases, write to auc-tex-request@iesd.auc.dk to join it.  Send contributions to auc-tex@iesd.auc.dk.

Bug reports, suggestions for new features, and pleas for help should go to either auc-tex_mgr@iesd.auc.dk (the AUC TeX managers), or to auc-tex@iesd.auc.dk (the mailing list) if they might have general interest.

Copying
*******

(This text stolen from the TeXinfo 2.16 distribution).

The programs currently being distributed that relate to AUC TeX include lisp files for GNU Emacs, plus other separate programs (specifically lacheck).  These programs are free; this means that everyone is free to use them and free to redistribute them on a free basis.  The AUC TeX 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 AUC TeX, 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 AUC TeX 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 AUC TeX. 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 AUC TeX are found in the General Public Licenses that accompany them.

Introduction
************

AUC TeX is a comprehensive customizable integrated environment for writing input files for LaTeX using GNU Emacs.

AUC TeX lets you run TeX/LaTeX and other LaTeX-related tools, such as output filters or post processors from inside Emacs.  Especially `running LaTeX' is interesting, as AUC TeX 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.

AUC TeX automatically indents your `LaTeX-source', not only as you write it---you can also let it indent and format an entire document.  It has a special outline feature, which can greatly help you `getting the overview' of a document.

Apart from these special features, AUC TeX provides a large range of handy Emacs macros, which in several different ways can help you write your LaTeX documents fast and without pain.  Here's a short list of the major features:

  * Insertion of templates for logical-structural compositions such as environments and sections.

  * Hot-keys for easy access to certain often used constructs, e.g., font changes, accented letters, and mathematical symbols.

  * Running application programs (such as TeX), and then parsing the output so that errors in the document may be located easily.

  * Support for multi-file documents.

  * Online help for (La)TeX error messages.

  * Outlining---i.e., manipulating the document as a composition of nested/sequential logical constructs.

  * Instant formatting and indentation of the ASCII-document in order to make it easier to read.

  * `Completion' (and thereby spell-checking) of partially written control sequences.

Inserting Frequently Used Commands
**********************************

The most commonly used commands/macros of AUC TeX are those which simply insert templates for often used TeX and/or LaTeX constructs, like font changes, handling of environments, etc. These features are very simple, and easy to learn, and help you avoiding stupid mistakes like mismatched braces, or \begin{}-\end{} pairs.

Insertion of Quotes Dollars, and Braces
=======================================

In TeX literal double quotes "like this" are seldom used, instead two single quotes are used ``like this''.  To help you insert these efficiently, AUC TeX allows you to continue to press " to insert two single quotes.  To get a literal double quote, press " twice.

 -- Command: TeX-insert-quote COUNT
     (") Insert the appropriate quote marks for TeX.

     Inserts the value of tex-open-quote (normally ``) or tex-close-quote (normally '') depending on the context. With prefix argument, always inserts " characters.

 -- User Option: TeX-open-quote
     String inserted by typing " to open a quotation.

 -- User Option: TeX-close-quote
     String inserted by typing " to open a quotation.

If you include the style file german TeX-open-quote and TeX-close-quote will both be set to ".

In AUC TeX, dollar signs should match like they do in TeX.  This has been parially implemented, we assume dollar signs always match within a paragraph.  The first $ you insert in a paragraph will do nothing special.  The second $ will match the first.  This will be indicated by moving the cursor temporarily over the first dollar sign.  If you enter a dollar sign that matches a double dollar sign $$ AUC TeX will automatically insert two dollar signs.  If you enter a second dollar sign that matches a single dollar sign, the single sollar sign will automatically be converted to a double dollar sign.

 -- Command: TeX-insert-dollar ARG
     ($) Insert dollar sign.

     Show matching dollar sign if this dollar sign end the TeX math mode. Ensure double dollar signs match up correctly by inserting extra dollar signs when needed.

     With optional ARG, insert that many dollar signs.

To avoid unbalanced braces, it is useful to insert them pairwise.  You can do this by typing C-c {.

 -- Command: TeX-insert-braces
     (C-c {) Make a pair of braces and position the cursor to type inside of them.

Inserting Font Specifiers
=========================

Perhaps the most used keyboard commands of AUC TeX are the short-cuts available for easy insertion of font changing macros.  They all put the font change inside a TeX group, a practice that help preventing subtle errors.  The most significant advantage of using these command instead of typing it in yourself, is that the braces will always match correctly.

If you give an argument (that is, type 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 -!- indicating the position where the text will be inserted.

C-c C-f C-r
     Insert roman {\rm -!-} text.

C-c C-f C-b
     Insert bold face {\bf -!-} text.

C-c C-f C-i
     Insert italics {\it -!-\/} text.

C-c C-f C-e
     Insert emphasized {\em -!-\/} text.

C-c C-f C-s
     Insert slanted {\sl -!-\/} text.

C-c C-f C-t
     Insert typewriter {\tt -!-} text.

C-c C-f C-c
     Insert SMALL CAPS {\sc -!-} text.

C-c C-f C-d
     Delete the innermost font specification containing point.

 -- Command: TeX-font ARG
     (C-c C-f) Insert template for font change command.

     If REPLACE is not nil, replace current font.  WHAT determines the font to use, as specified by TeX-font-list.

 -- User Option: TeX-font-list
     List of fonts used by 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.

Inserting chapters, sections, etc.
==================================

Insertion of sectioning macros, that is \chapter, \section, \subsection, etc. and accompanying \label's may be eased by using 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 AUC TeX, 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 LaTeX-section-hooks.

 -- Command: LaTeX-section ARG
     (C-c C-s) Insert a sectioning command.

     Determine the type of section to be inserted, by the argument ARG.

       * If ARG is nil or missing, use the current level.

       * If ARG is a list (selected by C-u), go downward one level.

       * If ARG is negative, go up that many levels.

       * If ARG is positive or zero, use absolute level:

            + 0 : part

            + 1 : chapter

            + 2 : section

            + 3 : subsection

            + 4 : subsubsection

            + 5 : paragraph

            + 6 : subparagraph

     The following variables can be set to customize the function.

     LaTeX-section-hooks
          Hooks to be run when inserting a section.

     LaTeX-section-label
          Prefix to all section references.

The precise behavior of LaTeX-section is defined by the contents of LaTeX-section-hooks.

 -- User Option: LaTeX-section-hooks
     List of hooks to run when a new section is inserted.

     The following variables are set before the hooks are run

     level
          Numeric section level, default set by prefix arg to LaTeX-section.

     name
          Name of the sectioning command, derived from LEVEL.

     title
          The title of the section, default to an empty string.

     toc
          Entry for the table of contents list, default nil.

     done-mark
          Position of point afterwards, default nil meaning after the inserted text.

     A number of hooks are already defined.  Most likely, you will be able to get the desired functionality by choosing from these hooks.

     LaTeX-section-level-hook
          Query the user about the name of the sectioning command.  Modifies LEVEL and NAME.

     LaTeX-section-title-hook
          Query the user about the title of the section. Modifies TITLE.

     LaTeX-section-toc-hook
          Query the user for the toc entry.  Modifies TOC.

     LaTeX-section-section-hook
          Insert LaTeX section command according to NAME, TITLE, and TOC.  If TOC is nil, no toc entry is inserted.  If TOC or TITLE are empty strings, DONE-MARK will be placed at the point they should be inserted.

     LaTeX-section-label-hook
          Insert a label after the section command.  Controlled by the variable LaTeX-section-label.

     To get a full featured LaTeX-section command, insert

          (setq LaTeX-section-hooks
                '(LaTeX-section-level-hook
                  LaTeX-section-title-hook
                  LaTeX-section-toc-hook
                  LaTeX-section-section-hook
                  LaTeX-section-label-hook))

     in your .emacs file.

The behavior of LaTeX-section-label-hook is determined by the variable LaTeX-section-label.

 -- User Option: 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.

     By default, chapters have a prefix of cha: while sections and subsections have a prefix of sec:.  Labels are not automatically inserted for other types of sections.

Inserting Environment Templates
===============================

A large apparatus is available that supports insertions of environments, that is \begin{} --- \end{} pairs.

AUC TeX is aware of most of the actual environments available in a specific document.  This is achieved by examining your \documentstyle command, and consulting a precompiled list of environments available in a large number of styles.

You insert an environment with C-c C-e, and select an environment type.  Depending on the environment, AUC TeX may ask more questions about the optional parts of the selected environment type.

 -- Command: LaTeX-environment
     (C-c C-e)  AUC TeX will prompt you for an environment to insert.  At this prompt, you may press TAB or SPC to complete a partially written name, and/or to get a list of available environments.  After selection of a specific environment AUC TeX may prompt you for further specifications.

As a default selection, AUC TeX will suggest the environment last inserted or, as the first choice the value of the variable LaTeX-default-environment.

 -- User Option: LaTeX-default-environment
     Default environment to insert when invoking LaTeX-environment.

If the document is empty, or the cursor is placed at the top of the document, AUC TeX will default to insert a `document' environment.

Most of these are described further in the following sections, and you may easily specify more, as described in `Customizing environments'.

You can close the current environment with C-c ], but we suggest that you use C-c C-e to insert complete environments instead.

 -- Command: LaTeX-close-environment
     (C-c ]) Insert an \end that matches the current environment.

Floats
------

Figures and tables (i.e., floats) may also be inserted using AUC TeX. After choosing either `figure' or `table' in the environment list described above, you will be prompted for a number of additional things.

float-to
     This field is the option of float environments that controls how they are placed in the final document.  In LaTeX this is a sequence of the letters htbp as described in the LaTeX manual.  The value will default to the value of LaTeX-float.

caption
     This is the caption of the float.

label
     The label of this float.  The label will have a default prefix, which is controlled by the variables LaTeX-figure-label and LaTeX-table-label.

Moreover, in the case of a `figure' environment, you will be asked if you want to insert a `center' environment inside the figure.

 -- User Option: LaTeX-float
     Default placement for floats.

 -- User Option: LaTeX-figure-label
     Prefix to use for figure labels.

 -- User Option: LaTeX-table-label
     Prefix to use for table labels.

Itemize-like
------------

In an itemize-like environment, nodes (i.e., \items) may be inserted using C-c LFD.

 -- Command: LaTeX-insert-item
     (C-c LFD) Close the current item, move to the next line and insert an appropriate \item for the current environment. That is, `itemize' and `enumerate' will have \item  inserted, while `description' will have \item[] inserted.

Tabular-like
------------

When inserting Tabular-like environments, that is, `tabular' `array' etc., you will be prompted for a template for that environment.

Customizing environments
------------------------

See Adding Environments, for how to customize the list of known environments.

Advanced Editing Features
*************************

The previous chapter described how to write the main body of the text easily and with a minimum of errors.  In this chapter we will describe some features for entering more specialized sorts of text, and for indenting and navigating through the document.

Entering Mathematics
====================

TeX is written by a mathematician, and has always contained good support for formatting mathematical text.  AUC TeX supports this tradition, by offering a special minor mode for entering text with many mathematic symbols.  You can enter this mode by typing C-c ~.

 -- Command: LaTeX-math-mode
     (C-c ~) Toggle LaTeX-math-mode.  This is a minor mode rebinding the key LaTeX-math-abbrev-prefix to allow easy typing of mathematical symbols.  ` will read a character from the keyboard, and insert the symbol as specified in LaTeX-mathlist.  If given a prefix argument, the symbol will be surrounded by dollar signs.

You can use another prefix key (instead of `) by  setting the variable LaTeX-math-abbrev-prefix.

 -- User Option: LaTeX-math-abbrev-prefix
     A string containing the prefix of LaTeX-math-mode commands; This value defaults to `.

The variable LaTeX-mathlist holds the actual mapping.

 -- User Option: LaTeX-mathlist
     A list containing key-command mappings to use in LaTeX-math-mode. The car of each element is the key and the cdr is the macro name.

Completion
==========

Emacs lisp programmers probably know the lisp-complete-symbol command, usually bound to M-TAB.  Users of the wonderful ispell mode know and love the ispell-complete-word command from that package.  Similarly, AUC TeX has a TeX-complete-symbol command, usually bound to C-c TAB.  Using LaTeX-complete-symbol makes it easier to type and remember the names of long LaTeX macros.

In order to use TeX-complete-symbol, you should write a backslash and the start of the macro.  Typing C-c TAB will now complete as much of the macro, as it unambiguously can.  For example, if you type `\renewc' and then `C-c TAB, it will expand to `\renewcommand'.

 -- Command: TeX-complete-symbol
     (C-c TAB)  Complete TeX symbol before point.

A more direct way to insert a macro is with TeX-insert-macro, bound to C-c C-m.  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 \include. Some examples are listed below.

 -- Command: TeX-insert-macro
     (C-c C-m) Prompt (with completion) for the name of a TeX macro, and if AUC TeX knows the macro, prompt for each argument.

Completions work because AUC TeX can analyze TeX files, and store symbols in emacs lisp files for later retrieval.  See Automatic, for more information.

Commenting
==========

It is often necessary to comment out temporarily a region of TeX or LaTeX code.  This can be done with the commands C-c ; and C-c %.  C-c ; will comment out all lines in the current region, while C-c % will comment out the current paragraph.  To uncomment, simply type C-u C-c ; to uncomment all lines in the region, or C-u C-c % uncomment all comment lines around point.

By default, these commands will insert or remove a single %.  To insert more than one, give an argument. C-u 5 C-c % will add five % to each line, while C-u - 5 C-c % will remove up to 5 % from each line.

 -- Command: TeX-comment-region COUNT
     (C-c ;) Add or remove % from the beginning of each line in the current region, as specified by COUNT.

     If COUNT is nil (no prefix argument), 1 % will be added to each line.

     If COUNT is a list (a non-numeric prefix argument), 1 % will be removed from each line.

     If COUNT is positive, COUNT %'s will be added to each line.

     If COUNT is negative, COUNT %'s will be removed from each line.

 -- Command: TeX-comment-paragraph COUNT
     (C-c %) Add or remove % from the beginning of each line in the current paragraph, as specified by COUNT.  When removing %'s the paragraph is considered to consist of all preceding and succeeding lines starting with a %, until the first non-comment line.

     If COUNT is nil (no prefix argument), 1 % will be added to each line.

     If COUNT is a list (a non-numeric prefix argument), 1 % will be removed from each line.

     If COUNT is positive, COUNT %'s will be added to each line.

     If COUNT is negative, COUNT %'s will be removed from each line.

Marking, Formatting and Indenting
=================================

AUC TeX contains very advanced handling of indentation and reformatting of the LaTeX source.  If you have already tried AUC TeX with auto-fill-mode enabled, you may have noted that the source is automatically indented and formatted as you write it.  More over, AUC TeX is able to format sections of text on demand.

It is important to realize, that AUC TeX comes with `formatting' in two fashions.  Either letting TeX format the file, or letting AUC TeX make the ASCII document look better.

Indentation is done by LaTeX environments and by TeX groups, that is the body of an environment is indented by the value of LaTeX-indent-level (default 2).  Also, items of an `itemize-like' environment are indented by the value of LaTeX-item-indent, default -2.  This indentation makes it easier to see the structure of the document, and to catch errors such as a missing close brace.  Thus, the indentation is done for precisely the same reasons that you would indent ordinary computer programs.

The following is a short sample of an itemize environment indented by AUC TeX.  If more environment are nested, they are indented `accumulated' just like most programming languages usually are seen indented in nested constructs.

     \begin{itemize}
     \item Insertion of templates for logical-structural compositions such as
       environments and sections.
     \item Hot-keys for easy access to certain often used constructs, e.g.,
       font changes, accented letters, and mathematical symbols.
     \item Running application programs (such as \TeX), and then parsing
       the output so that errors in the document may be located
       easily.
     \item Support for multi-file documents.
     \item Online help for \AllTeX\ error messages.
     \item Outlining\Dash i.e., manipulating the document as a composition
       of nested/sequential logical constructs.
     \item Instant formatting and indentation of the \ascii-document in
       order to make it easier to read.
     \item `Completion' (and thereby spell-checking) of partially written
       control sequences.
     \end{itemize}

You can format and indent single lines, paragraphs, environments, or sections.

TAB
     LaTeX-indent-line will indent the current line.

LFD
     reindent-then-newline-and-indent indents the current line, and then inserts a new line (much like RET) and move the cursor to an appropriate position by the left margin.

M-q
     Alias for C-c C-q C-p

C-c C-q C-p
     LaTeX-format-paragraph will reformat or `fill' the current paragraph.

C-c C-q C-e
     LaTeX-format-environment will reformat or `fill' the current environment.  This may e.g. be the `document' environment, in which case the entire document will be formatted.

C-c C-q C-s
     LaTeX-format-section will reformat or `fill' the current logical sectional unit.

M-g
     Alias for C-c C-q C-r

C-c C-q C-r
     LaTeX-format-region will format or `fill' the current region.

Warning: The formatting cannot handle tabular-like environments. Those will be completely messed-up if you try to format them.

 -- User Option: LaTeX-indent-level
     Number of spaces to add to the indentation for each \begin not matched by a \end.

 -- User Option: LaTeX-item-indent
     Number of spaces to add to the indentation for \item's in list environments.

 -- User Option: TeX-brace-indent-level
     Number of spaces to add to the indentation for each { not matched by a }.

Outlining the Document
======================

Minor mode for editing outlines with selective display.  Headings are lines which start with asterisks: one for major headings, two for sub-headings, etc.  Lines not starting with asterisks are body lines.

Body text or sub-headings under a heading can be made temporarily invisible, or visible again.  Invisible lines are attached to the end of the heading, so they move with it, if the line is killed and yanked back.  A heading with text hidden under it is marked with an ellipsis (...).

C-c C-o C-n
     outline-next-visible-heading move by visible headings

C-c C-o C-p
     outline-previous-visible-heading

C-c C-o C-f
     outline-forward-same-level similar but skip sub-headings

C-c C-o C-b
     outline-backward-same-level

C-c C-o C-u
     outline-up-heading move from sub heading to heading

C-c C-o C-t
     hide-body make all text invisible (not headings).

C-c C-o C-a
     show-all make everything in buffer visible.

C-c C-o C-o
     outline-minor-mode leave outline mode.

The remaining commands are used when point is on a heading line. They apply to some of the body or sub-headings of that heading.

C-c C-o C-h
     hide-subtree make body and sub-headings invisible.

C-c C-o C-s
     show-subtree make body and sub-headings visible.

C-c C-o C-i
     show-children make direct sub-headings visible.  No effect on body, or sub-headings 2 or more levels down. With arg N, affects sub-headings N levels down.

C-c C-o C-c
     hide-entry make immediately following body invisible.

C-c C-o C-e
     show-entry make it visible.

C-c C-o C-l
     hide-leaves make body under heading and under its sub-headings invisible. The sub-headings remain visible.

C-c C-o C-x
     show-branches make all sub-headings at all levels visible.

 -- User Option: outline-prefix-char
     The prefix char (C-c C-o) used to activate the outline commands. You most likely want to set this to something shorter.

In LaTeX mode the default headings are the sectioning commands, and as top level headings \documentstyle, \appendix, TeX-trailer-start, and TeX-header-end.  You can also define extra headings at any level, by setting the variable TeX-outline-extra.

 -- User Option: 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. See LaTeX-section-list for existing header levels.

You can use outlining in other modes as well, the function to do this is outline-minor-mode.

 -- Command: outline-minor-mode PREFIX
     Enters outline minor mode.  With PREFIX: non-nil: turn outline mode on.  nil: turn outline mode off.

 -- User Option: outline-regexp
     Regular expression matching header lines.  When using outline-minor mode outside AUC TeX, this is per default set to lines beginning with one or more stars.

 -- User Option: outline-level-function
     Function calculating the level of a header.  Outside AUC TeX, this is per default the length of the string matched by outline-regexp.

Formatting and Printing
***********************

The most powerful features of AUC TeX may be those allowing you to run (La)TeX and other external commands like BibTeX and makeindex from within Emacs, viewing and printing the results, and moreover allowing you to debug your documents.

Executing Commands
==================

Formatting the document with TeX or LaTeX, viewing with a a previewer, printing the document, running BibTeX, making an index, or checking the document with lacheck all require running an external command.

There are two ways to run an external command, you can either run it on all of the current document with TeX-command-master, or on the current region with TeX-command-region.

 -- Command: TeX-command-master
     (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 TeX-master.  The available commands are controlled by the variable TeX-command-list.

See Installation for a discussion about TeX-command-list and Multifile for a discussion about TeX-master.

 -- Command: TeX-command-region
     (C-c C-r)  Query the user for a command, and run it on the ``region file''.  Some commands (typically those invoking TeX or LaTeX) will write the current region into the region file, after extracting the header and tailer from the master file.  The name of the region file is controlled by the variable TeX-region.  The name of the master file is controlled by the variable TeX-master.  The header is all text up to the line matching the regular expression TeX-header-end.  The trailer is all text from the line matching the regular expression TeX-trailer-start.  The available commands are controlled by the variable TeX-command-list.

AUC TeX will allow one process for each document, plus one process for the region file to be active at the same time.  Thus, if you are editing N different documents, you can have N plus one processes running at the same time.  If the last process you started was on the region, the commands described in Debugging and Control will work on that process, otherwise they will work on the process associated with the current document.

 -- User Option: TeX-region
     The name of the file for temporarily storing the text when formatting the current region.

 -- User Option: TeX-header-end
     A regular expression matching the end of the header.  By default, this is \begin{document} in LaTeX mode and %**end of header in TeX mode.

 -- User Option: TeX-trailer-start
     A regular expression matching the start of the trailer.  By default, this is \end{document} in LaTeX mode and \bye in TeX mode.

AUC TeX will try to guess what command you want to invoke, but by default it will assume that you want to run TeX in TeX mode and LaTeX in LaTeX mode.  You can overwrite this by setting the variable TeX-command-default.

 -- User Option: TeX-command-default
     The default command to run in this buffer.  Must be an entry in TeX-command-list.

If you want to overwrite the values of TeX-header-end, TeX-trailer-start, or TeX-command-default, you can do that for all files by setting them in either TeX-mode-hook, plain-TeX-mode-hook, or LaTeX-mode-hook.  To overwrite them for a single file, define them as file variables (see File Variables (The Emacs Editor)).  You do this by putting special formatted text near the end of the file.

     % Local Variables:
     % TeX-header-end: "% End-Of-Header"
     % TeX-trailer-start: "% Start-Of-Trailer"
     % TeX-command-default: "SliTeX"
     % End:

Catching the errors
===================

Once you've formatted your document you may `debug' it, i.e. browse through the errors (La)TeX reported.

 -- Command: TeX-next-error
     (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.

Normally AUC TeX will only report real errors, but you may as well ask it to report `bad boxes' as well.

 -- Command: TeX-toggle-debug-bad-boxes
     (C-c C-w)  Toggle whether AUC TeX should stop at bad boxes (i.e. over/under full boxes) as well as at normal errors.

As default, AUC TeX will display that 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.

 -- User Option: TeX-display-help
     When non-nil AUC TeX will automatically display a help text whenever an error is encountered using TeX-next-error (C-c `).

Checking for problems
=====================

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 utility lacheck can be used to find style errors, such as forgetting to escape the space after an abbreviation or using ... instead of \ldots and many other problems like that.  You start lacheck with C-c C-c C h e c k RET.  The result will be a list of errors in the *compilation* buffer.  You can go through the errors with C-x ` (next-error, see Compilation (The Emacs Editor)), which will move point to the location of the next error.

Controlling the output
======================

A number of commands are available for controlling the output of an application running under AUC TeX

 -- Command: TeX-kill-job
     (C-c C-k)  Kill currently running external application. This may be either of TeX, LaTeX, previewer BibTeX etc.

 -- Command: TeX-recenter-output-buffer
     (C-c C-l)  Recenter the output buffer so that the bottom line is visible.

 -- Command: TeX-home-buffer
     (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.

Multifile Documents
*******************

If you 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 (see Outline)), that can be done by having a ``master'' file from where you include the various files with the TeX macro \input or the LaTeX macro \include.  These files may also include other files themselves.  However, to format the document you must run the commands on the top level file.

When you for example ask AUC TeX to run a command on the master file, it has no way to know what the name of the master file is.  If it finds the line indicating the end of the header in a master file (TeX-header-end), it can figure out for itself that this is a master file.  Otherwise, it will ask for the name of the master file associated with the buffer.  To avoid asking you again, AUC TeX will automatically insert the name of the master file as a file variable (see File Variables (The Emacs Editor)).  You can also insert the file variable yourself, by putting the following text at the end of your files.

     % Local Variables:
     % TeX-master: "mymaster"
     % End:

You should always set this variable to the top level document.  If you always use single file documents, or always use the same name for your top level documents, you can set this variable in your .emacs file.

     (setq-default TeX-master t) ; Only use single file douments.

     (setq-default TeX-master "master") ; All master files called "master".

 -- User Option: TeX-master
     The master file associated with the current buffer.  If the file being edited is actually included from another file, you can tell AUC TeX 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 nil, AUC TeX will query you for the name.

     If the variable is t, AUC TeX will assume the file is a master file itself.

     If the variable is 'shared, AUC TeX will query for the name, but not change the file.

     It is suggested that you use the File Variables (see File Variables (The Emacs Editor)) to set this variable permanently for each file.

 -- User Option: TeX-one-master
     Regular expression matching ordinary TeX files.

     You should set this variable to match the name of all files, where automatically adding a file variable with the name of the master file is a good idea.  When AUC TeX 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 AUC TeX automatically modifying your files, you can set this variable to "<none>". By default, AUC TeX will modify any file with an extension of .tex.

AUC TeX keeps track of macros, environments, labels, and style files that are used in a given document.  For this to work with multifile documents, AUC TeX has to have a place to put the information about the files in the document.  This is done by having an auto subdirectory placed in the directory where your document is located.  Each time you save a file, AUC TeX will write information about the file into the auto directory.  When you load a file, AUC TeX will then read the information in the auto directory about the file you loaded, and the master file specified by TeX-master.  Since the master file (perhaps indirectly) includes all other files in the document, AUC TeX will get information from all files in the document.  This means that you will get from each file e.g. completion for all labels defined anywhere in the document.

You must create the auto directory manually for this to work.  If you don't do this, the other files in the document will not know anything about each other, except for the name of the master file. See Automatic Local.

Automatic Parsing of TeX files.
*******************************

AUC TeX depends heavely on being able to extract information from the buffers by parsing them.  Since parsing the buffer can be somewhat slow, AUC TeX will store the parsed information in an auto subdirectory in the directory where the TeX files are stored, see Automatic Local.  The information in the auto directory is also useful for multifile documents see 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.

When you issue the first AUC TeX command on a new buffer, AUC TeX will try to read the information about the file from the auto directory.  If this fails, for example if you have not edited the file before, it will parse the current buffer.

When you save the buffer it will be parsed again, and the information will be placed in the auto directory for use next time the file -- or another file in the document -- is edited.

It is possible to disable the parsing by setting the buffer local variables TeX-parse-self and TeX-auto-save.

     (setq-default TeX-parse-self nil) ; Disable parse on load.
     (setq-default TeX-auto-save nil) ; Disable parse on save.

This can also be done on a per file basis, by changing the file local variables.

     % Local Variables:
     % TeX-parse-self: nil
     % TeX-auto-save: nil
     % End:

Even when you have disabled the automatic parsing, you can force the generation of style information by pressing C-c C-n.

 -- User Option: TeX-parse-self
     Parse file after loading it if no style hook is found for it.

 -- User Option: TeX-auto-save
     Automatically save style information when saving the buffer.

 -- Command: TeX-normal-mode ARG
     (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.

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 TeX-auto-regexp-list and TeX-auto-parse-length in your .emacs file.

     ;; Only parse \documentstyle information.
     (setq-default TeX-auto-regexp-list 'LaTeX-auto-minimal-regexp-list)
     ;; The documentstyle command is usually near the beginning.
     (setq-default TeX-auto-parse-length 2000)

This example will speed the parsing up significantly, but AUC TeX will not longer be able to provide completion for labels, macros, environments, or bibitems specified in the document, not 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.

     % Local Variables:
     % TeX-auto-regexp-list: TeX-auto-full-regexp-list
     % TeX-auto-parse-length: 999999
     % End:

 -- User Option: TeX-auto-regexp-list
     List of regular expresions used for parsing the current file.

 -- User Option: TeX-auto-parse-length
     Maximal length of TeX file that will be parsed.

The pre-specified lists of regexps are defined below.  You can use these before loading AUC TeX by quoting them, as in the example above.

 -- Constant: LaTeX-auto-minimal-regexp-list
     Only parse documentstyle.

 -- Constant: LaTeX-auto-label-regexp-list
     Only parse LaTeX labels.

 -- Constant: LaTeX-auto-regexp-list
     Parse common LaTeX commands.

 -- Constant: plain-TeX-auto-regexp-list
     Parse common plain TeX commands.

 -- Constant: TeX-auto-full-regexp-list
     Parse all TeX and LaTeX commands that AUC TeX can use.

The Anti-American Conspiracy
****************************

AUC TeX contains some support for ease the use of various European character sets.  This support is contained in two packages ``Keymap Mode'' in min-key.el, which support general remapping of the keyboard, as well as converting between various character set encodings, and ``Dead Key Mode'' in ltx-dead.el, which support dead keys for entering accents.  Both packages depend on the ``Minor Mode Keymap'' support in min-bind.el, but at least ``Keymap Mode'' is otherwise useful even outside AUC TeX.

If you have the necessary software, AUC TeX will also work with some Japanese versions of TeX and Emacs.

Support for the Scandinavian Languages
======================================

For some languages, it makes sense to remap the keyboard.  This is true for languages that add a small set of regular letters compared to the English character set.  The Scandinavian languages belong to this category.  Danish, Norwegian, and Swedish each add three extra letters compared to English, all of which are equal to the other letters in the alphabet.  They are not considered accented versions of the ``regular'' letters.

Since these letters have a well defined place on any Scandinavian keyboard, it makes sense to remap these keys to insert the equivalent TeX macros.  This can also be done on a keyboard with international layout, just map the keys at the locations where the national letters normally are found.

In order to get the original binding of the keys, we can use a little trick.  If you press one of the national keys twice, the national letter will first be inserted, and then replaced with the original binding of the key.  This works since these national letters practically never occur twice in row in a Scandinavian word.

The keyboard mapping is implemented as a minor mode.  To enter the minor mode for the first time, type M-x keyboard-query-mapping.  It will first prompt you for a language to use.  Currently only Danish, Swedish, German, and Russian are defined, so you have to chose one of those.  Norway use the same character set as Denmark.

Next, it will prompt you for what encoding of the language's character set to use for the keyboard and screen.  The same encodings are available for both the keyboard and screen, but they are not equally good.  Choosing e.g. TeX for the keyboard encoding is not very useful. Below is a table of currently supported encodings.

ISO 646 (DK or SE)

     If your terminal thinks {, |, and } are letters, this is the encoding for you.  You can use it for either Keyboard or Screen encoding.

Keyboard Layout

     If you have an international keyboard layout, use this for the keyboard encoding.  If you do not have an international keyboard layout -- but wish you had -- you can use it for the Screen encoding instead.

Digraphs

     Two letter combinations that form poor substitutes for the real national letters.  It can be used as the Screen encoding, if you for example are sending electronic mail to someone on an unknown machine.

TeX

     This is what you want to use for the Screen encoding when writing a TeX document.

ISO 8859 Latin 1

     Only useful if you have hacked Emacs to understand 8-bit characters.

Finally, it will ask you if you want to get the original binding by pressing a key twice.  For the Scandinavian languages, you want this.

 -- Command: keyboard-query-mapping
     (M-x keyboard-query-mapping) Query the user for what mapping to use, and use it.

After you have entered keyboard-mode once, you can leave and enter it with M-x keyboard-mode.  It will use the same mapping as last time you called keyboard-query-mapping.

 -- Command: keyboard-query-mapping
     (M-x keyboard-mode) Toggle keyboard-mode. With prefix arg, turn keyboard-mode on iff arg is positive.

This is still inconvenient, so you may want to define a special function to turn your favorite mapping on and of, as shown in the following example.

     (defun tex-dk-double-mode (arg)
       "DK TeX keys on international keyboard."
       (interactive "P")
       (require 'min-key)
       (if (or (and (null arg) keyboard-mode)
               (<= (prefix-numeric-value arg) 0))
           (keyboard-mode -1)
         (keyboard-set-mapping "Danish" "Keyboard Layout" "TeX" t)
         (keyboard-mode 1)))

To enter new character sets or new encodings, you must edit the variable language-encodings in the file min-key.el.  Please send any new useful additions to me.

 -- User Option: language-encodings
     Language dependent mapping between different encodings.

     This list determines how to map between different encodings of the character set of a language.

     Each element in the list is itself a list.

     The first element is the name of the language.

     The second element is a short name of the language.

     The third element is a list of short strings, each representing a possible encoding of the language's character set.

     The fourth element is a list of long strings, each representing the same encodings of the language's character set.

     The remaining elements each represent the encodings of one character. The encodings must appear in the same sequence as they were found in the second element.

Support for Russian
===================

See Scandinavian for a general explanation of keyboard remapping.

For Russian it not only makes sense to remap the keyboard.  You have to do it, in order to get the Cyrillic character set from an ordinary QWERTY keyboard.  AUC TeX will map QWERTY into the Russian keyboard layout YAWERTY, either with AMS Cyrillic encoding or the KOI8 character set encoding.  The standard Russian keyboard layout JCUKEN is not implemented, contributions welcome.

The Russian character set encodings were kindly contributed by Justin R. Smith <jsmith@king.mcs.drexel.edu>, please direct questions to him.

You can get a Cyrillic font for X11 from Serge Vakulenko <vak@kiae.su>.  You will need an Emacs capable of displaying 8 bit characters to use it.

             ---------------------------------------------
             | English        Russian         Mixed      |
             | keyboard       keyboard       keyboard    |
             |                                           |
             |  qwerty         jcuken        yawerty     |
             |-------------------------------------------|
             |   q Q      i-short I-short     ya Ya      |
             |   w W          tse Tse         ve ve      |
             |   e E            u U           ie Ie      |
             |   r R           ka Ka          ar Er      |
             |   t T           ie Ie          te Te      |
             |   y Y           en En        iery Iery    |
             |   u U          ghe Ghe          u U       |
             |   i I          sha Sha          i I       |
             |   o O        shcha Shcha        o O       |
             |   p P            z Z           pe Pe      |
             |   a A           ef Ef           a A       |
             |   s S         iery Iery        es Es      |
             |   d D           ve ve          de De      |
             |   f F            a A           ef Ef      |
             |   g G           pe Pe          ge Ge      |
             |   h H           er Er         kha Kha     |
             |   j J            o O      i-short I-short |
             |   k K           el El          ka Ka      |
             |   l L           de De          el El      |
             |   z Z           ya Ya           z Z       |
             |   x X          che Che        ier Ier     |
             |   c C           es Es         tse Tse     |
             |   v V           em Em         zhe Zhe     |
             |   b B            i I           be Be      |
             |   n N           te Te          en En      |
             |   m M        ierik Ierik       em Em      |
             |                                           |
             |   [ {          kha Kha        sha Sha     |
             |   ] }          ier Ier      shcha Shcha   |
             |   ; :          zhe Zhe                    |
             |   ' "        e-rev E-rev                  |
             |   , <           be Be                     |
             |   . >           yu Yu                     |
             |   ` ~                          yu Yu      |
             |   3 #                           3 ier     |
             |   4 $            4 "                      |
             |   5 %            5 :                      |
             |   6 ^            6 ,                      |
             |   7 &            7 .                      |
             |   = +                         che Che     |
             |   \ |                       e-rev E-rev   |
             ---------------------------------------------

Dvorak and QWERTY
=================

QWERTY is a well established standard for how the keys on a keyboard are placed.  It is almost universally accepted, most countries use it with only minor modifications to allow for any additional letters.  However, it is far from optimal.  It is even said that QWERTY was purposefully designed to slow down the typist, in order to protect the early typewriters.

Modern research has shown that large speedups in typing can be obtained by designing a new keyboard radically different from the current standard.  Specifically, it should be split in two, and characters should be entered by pressing several keys at once.

However, some small speedups can be obtained simply by remapping the keys using the same physical layout.  The Dvorak layout is an example of this.  It is usually not worth the frustration of having to master a different keyboard layout, but some people have made the effort.

With keyboard-mode you can use QWERTY layout on a Dvorak keyboard, or vice versa.  Simply type M-x keyboard-query-mapping, select the ``language'' Keyboard Layout, and specify the layout on the keyboard, and what layout you want on the screen.  Answer n when it asks you about pressing the key twice to get the original binding.  You can then switch between QWERTY and Dvorak with M-x keyboard-mode.

See Scandinavian for a more detailed description of these functions.

Accents on Dead Keys
====================

In some languages, like German and Dutch, you can make variants of certain letters by giving them an accent mark.  A common way to enter these combined characters on a typewriter is by first typing a ``dead'' key which prints the accent mark without moving the printers head, and then typing the letter.  In AUC TeX we simulate this by marking certain keys as dead.  When you press one of those keys, it will wait for another key to be pressed.  To enter the accent by itself, press the dead key twice.  Examples: ' e inserts \'{e}.  ' ' inserts '.  ' i inserts \'{\i}.

To enable this feature, you must first specify what accents you are interested in.  This is done by setting the variable LaTeX-dead-keys.

 -- User Option: LaTeX-dead-keys
     List of characters used as dead keys.  Valid characters are ', `, ", ^, and ~.  By default, all the valid characters are used.

This is best done in your .emacs file.  Then, you simply enable the dead keys with M-x LaTeX-dead-mode.

 -- Command: LaTeX-dead-mode
     (M-x LaTeX-dead-mode) Toggle LaTeX-dead-mode. With prefix arg, turn LaTeX-dead-mode on iff arg is positive.

     This mode allows users to conveniently enter characters with accents, as found in some European languages.

     The supported accents are defined by LaTeX-dead-keys.  Modify that variable to change the list of dead keys. (You most likely want to do that).

Converting Between Encodings of a Character Set
===============================================

You can convert between any of the encodings for any of the supported character sets, even the special character set called Keyboard Layout.  However, the most useful conversion is for the Latin1 character set.  You convert the current region by typing convert-character-query.  It will ask you for a character set and two encodings of the character set.

 -- Command: convert-character-query
     (convert-character-query) Convert characters in region, query user for character set and two encodings.

This function can be useful, not only when you want to import a file written with a different character set encoding, but also when you write TeX documents normally.  You can use this function to edit the TeX document using a character set that your terminal will display correctly, and then convert the file to TeX format before you format it.

Japanese TeX
============

To write Japanese text with AUC TeX you need to have versions of TeX and Emacs that support Japanese.  There exist at least two variants of TeX for Japanese text, and AUC TeX can be used with both, as well as with the two Japanese-aware Emacses, NEMACS and MULE.

To use the Japanese TeX variants, simply enter japanese-tex-mode, japanese-latex-mode, or japanese-slitex-mode, and everything should work.  If not, send mail to Shinji Kobayashi (<koba@flab.fujitsu.co.jp>, who kindly donated the code for supporting Japanese in AUC TeX.  None of the primary AUC TeX maintainers understand Japanese, so they can not help you.

Automatic Customization
***********************

Since AUC TeX 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 ~/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 you compare with the environment variable TEXINPUTS, the global level corresponds to the directories built into TeX.  The private level corresponds to the directories you add yourself, except for ., which is the local level.

By default AUC TeX 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 TeX-style-path are loaded, and all hooks defined in the files will be executed.

 -- User Option: TeX-style-path
     List of directories to search for AUC TeX style files. Each must end with a slash.

By default, when AUC TeX searches a directory for files, it will recursively search through subdirectories.

 -- User Option: TeX-file-recurse
     If not nil, search TeX directories recursively.

By default, AUC TeX will ignore files name ., .., SCCS, RCS, and CVS.

 -- User Option: 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.

Automatic Customization for the Site
====================================

Assuming that the automatic customization at the global level was done when AUC TeX 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 TeX-auto-global to nil.

 -- User Option: TeX-macro-global
     Directories containing the site's TeX style files.

 -- User Option: TeX-style-global
     Directory containing hand generated TeX information. Must end with a slash.

     These correspond to TeX macros shared by all users of a site.

 -- User Option: TeX-auto-global
     Directory containing automatically generated information.

     For storing automatic extracted information about the TeX macros shared by all users of a site.

Automatic Customization for a User
==================================

You should specify where you store your private TeX macros, so AUC TeX can extract their information.  The extracted information will go to the directory TeX-auto-private

Use M-x TeX-auto-generate to extract the information.

 -- User Option: TeX-macro-private
     Directories where you store your personal TeX macros. Each must end with a slash.

 -- User Option: TeX-auto-private
     Directory containing automatically generated information. Must end with a slash.

     These correspond to the personal TeX macros.

 -- Command: TeX-auto-generate TEX AUTO
     (M-x TeX-auto-generate) Generate style hook for TEX and store it in AUTO.  If TEX is a directory, generate style hooks for all files in the directory.

 -- User Option: TeX-style-private
     Directory containing hand generated information. Must end with a slash.

     These correspond to the personal TeX macros.

Automatic Customization for a Directory
=======================================

AUC TeX can update the style information about a file each time you save it, and it will do this if the directory TeX-auto-local exist. TeX-auto-local is by default set to "auto/", so simply creating an 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 TeX-auto-local to nil.

 -- User Option: TeX-style-local
     Directory containing hand generated TeX information. Must end with a slash.

     These correspond to TeX macros found in the current directory.

 -- User Option: TeX-auto-local
     Directory containing automatically generated TeX information. Must end with a slash.

     These correspond to TeX macros found in the current directory.

Writing Your own Style Support
******************************

See 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 style directories instead of auto directories.

If you write some useful support for a public TeX style file, please send it to us.

A Simple Style File
===================

Here is a simple example of a style file.

     ;;; book.el - Special code for book style.

     (TeX-add-style-hook "book"
      (function (lambda () (setq LaTeX-largest-level
                                 (LaTeX-section-level ("chapter"))))))

This file specifies that the largest kind of section in a LaTeX document using the book document style is chapter.  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 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 is executed.  The actual files will only be evaluated once, but the hooks will be called for each buffer using the style file.

 -- Function: TeX-add-style-hook STYLE HOOK
     Add HOOK to the list of functions to run when we use the TeX file STYLE.

Adding Support for Macros
=========================

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 latex.el.

     (TeX-add-style-hook "latex"
      (function
       (lambda ()
          (TeX-add-symbols
          '("arabic" TeX-argument-counter-hook)
          '("label" TeX-argument-define-label-hook)
          '("ref" TeX-argument-label-hook)
          '("newcommand" TeX-argument-define-macro-hook [ "Number of arguments" ] t)
          '("newtheorem" TeX-argument-define-environment-hook
            [ TeX-argument-environment-hook "Numbered like" ]
            t [ TeX-argument-counter-hook "Within counter" ])))))

 -- Function: TeX-add-symbols SYMBOL ...
     Add each SYMBOL to the list of known symbols.

Each argument to TeX-add-symbols is a list describing one symbol. The head of the list is the name if 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, AUC TeX will chose the one with the longest definition (i.e. the one with the most arguments).

Thus, to overwrite

             '("tref" 1) ; one argument

you can specify

             '("tref" TeX-argument-label-hook ignore) ; two arguments

ignore is a function that does not do anything, so when you insert a tref you will be prompted for a label and no more.

string
     Use the string as a prompt to prompt for the argument.

number
     Insert that many braces, leave point inside the first.

nil
     Insert empty braces.

t
     Insert empty braces, leave point between the braces.

other symbols
     Call the symbol as a function.  You can define your own hook, or use one of the predefined argument hooks.

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.

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.

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.

TeX-argument-conditional-hook
     Implements if EXPR THEN ELSE.  If EXPR evaluates to true, parse THEN as an argument list, else parse ELSE as an argument list.

TeX-argument-literal-hook
     Insert its arguments into the buffer.  Used for specifying extra syntax for a macro.

TeX-argument-free-hook
     Parse its arguments but use no braces when they are inserted.

TeX-argument-eval-hook
     Evaluate arguments and insert the result in the buffer.

TeX-argument-file-hook
     Prompt for a tex or sty filename, and use it without the extension. Run the file hooks defined for it.

TeX-argument-label-hook
     Prompt for a label completing with known labels.

TeX-argument-macro-hook
     Prompt for a TeX macro with completion.

TeX-argument-environment-hook
     Prompt for a LaTeX environment with completion.

TeX-argument-cite-hook
     Prompt for a BibTeX citation.

TeX-argument-counter-hook
     Prompt for a LaTeX counter.

TeX-argument-savebox-hook
     Prompt for a LaTeX savebox.

TeX-argument-file-hook
     Prompt for a filename in the current directory, and use it without the extension.

TeX-argument-input-file-hook
     Prompt for a filename in the current directory, and use it without the extension.  Run the style hooks for the file.

TeX-argument-define-label-hook
     Prompt for a label completing with known labels.  Add label to list of defined labels.

TeX-argument-define-macro-hook
     Prompt for a TeX macro with completion.  Add macro to list of defined macros.

TeX-argument-define-environment-hook
     Prompt for a LaTeX environment with completion.  Add environment to list of defined environments.

TeX-argument-define-cite-hook
     Prompt for a BibTeX citation.

TeX-argument-define-counter-hook
     Prompt for a LaTeX counter.

TeX-argument-define-savebox-hook
     Prompt for a LaTeX savebox.

TeX-argument-corner-hook
     Prompt for a LaTeX side or corner position with completion.

TeX-argument-lr-hook
     Prompt for a LaTeX side with completion.

TeX-argument-tb-hook
     Prompt for a LaTeX side with completion.

TeX-argument-pagestyle-hook
     Prompt for a LaTeX pagestyle with completion.

TeX-argument-verb-hook
     Prompt for delimiter and text.

TeX-argument-pair-hook
     Insert a pair of numbers, use arguments for prompt. The numbers are surrounded by parentheses and separated with a comma.

TeX-argument-size-hook
     Insert width and height as a pair.  No arguments.

TeX-argument-coordinate-hook
     Insert x and y coordinates as a pair.  No arguments.

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 exit-mark.  It will point nowhere, until the argument hook sets it.

Adding Support for Environments
===============================

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 latex.el.

     (TeX-add-style-hook "latex"
      (function
       (lambda ()
         (LaTeX-add-environments
          '("document" LaTeX-document-hook)
          '("enumerate" LaTeX-item-hook)
          '("itemize" LaTeX-item-hook)
          '("list" LaTeX-list-hook)))))

The only hook that is general useful is LaTeX-item-hook, which is used for environments that contain items.  It is completely up to the environment hook to insert the environment, but the function LaTeX-insert-environment may be to 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.

If an environment is defined multiple times, AUC TeX will chose 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 enumerate.el file as follows, and place it in the appropriate style directory.

     (TeX-add-style-hook "latex"
      (function
       (lambda ()
         (LaTeX-add-environments
          '("enumerate" LaTeX-enumerate-hook foo)))))

     (defun LaTeX-enumerate-hook (environment &optional ignore) ...)

The symbol foo will be passed to LaTeX-enumerate-hook as the second argument, but since we only added it to overwrite the definition in latex.el it is just ignored.

 -- Function: LaTeX-add-environments ENV ...
     Add each ENV to list of loaded environments.

 -- Function: LaTeX-insert-environment ENV [ EXTRA ]
     Insert environment of type ENV, with optional argument EXTRA.

Adding Other Information
========================

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.

 -- Function: LaTeX-add-bibliographies BIBLIOGRAPHY ...
     Add each BIBLIOGRAPHY to list of loaded bibliographies.

 -- Function: LaTeX-add-labels LABEL ...
     Add each LABEL to the list of known labels.

Supporting Other Format Packages
================================

You can add support for new TeX format packages.  These are treated specially, in that they are loaded immediately after you enter VirTeX-mode, and they actually define the major mode.

Here is the file defining slitex-mode.

     ;;;  SLITEX.el - Special code for SliTeX mode.

     (require 'tex-init)
     (require 'ltx-misc)

     (TeX-add-style-hook "SLITEX"
      (function
       (lambda ()
         (setq mode-name "SliTeX")
         (setq major-mode 'SliTeX-mode)
         (setq TeX-command-default TeX-command-SliTeX)
         (LaTeX-mode-initialization)
         (run-hooks 'SliTeX-mode-hook)
         (TeX-run-style-hooks "latex" "slitex"))))

The file should be placed in the directory TeX-format-directory.

 -- User Option: TeX-format-directory
     Directory containing information about TeX format packages. Must end with a slash.

You must also add an entry to TeX-format-list in order to make it known to the rest of the system.

 -- User Option: TeX-format-list
     List of format packages to consider when choosing a TeX mode.

     A list with an entry for each format package available at the site.

     Each entry is a list with three elements.

      1. The name of the format package.

      2. The name of the major mode.

      3. A regexp typically matched in the beginning of the file.

     When entering tex-mode, each regexp is tried in turn in order to find what major mode to enter.

Automatic Extraction of New Things
==================================

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 macro.tex I define the following macro.

     \newcommand{\newmacro}[5]{%
     \def#1{#3\index{#4@#5~cite{#4}}\nocite{#4}}%
     \def#2{#5\index{#4@#5~cite{#4}}\nocite{#4}}%
     }

AUC TeX will automatically figure out that 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.

     ;;; macro.el - Special code for my own macro file.

     ;;; New Macro Definition Command

     (require 'tex-auto)

     (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 ()
       "Support for \\newmacro macro."

       (mapcar (function (lambda (list)
                           (mapcar (function (lambda (symbol)
                                               (setq TeX-auto-symbol
                                                     (cons symbol
                                                           TeX-auto-symbol))))
                                   list)))
               TeX-auto-multi))

     (setq TeX-auto-prepare-hooks (cons (function (lambda ()
                                                      (setq TeX-auto-multi nil)))
                                        TeX-auto-prepare-hooks))

     (setq TeX-auto-cleanup-hooks (cons 'TeX-macro-cleanup TeX-auto-cleanup-hooks))

     ;;; HOOK

     (TeX-add-style-hook "macro"
      (function
       (lambda ()
         (TeX-auto-add-regexp TeX-newmacro-regexp)
         (TeX-add-symbols '("newmacro"
                            TeX-argument-macro-hook
                            (TeX-argument-macro-hook "Capitalized macro: \\")
                            t
                            "BibTeX entry: "
                            nil)))))

When this file is first loaded, it adds a new entry to 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 newmacro macro, as we have seen it before.

So the general strategy is: Add new entry to TeX-newmacro-regexp. Declare variable to contain intermediate data during parsing.  Add hook to be called before and after parsing.  In this case, the hook before parsing just initialize the variable, and the hook after parsing collect the data from the variable, and add them to the list of symbols found.

 -- Variable: TeX-auto-regexp-list
     List of regular expressions matching TeX macro definitions.

     The list has the following format ((REGEXP MATCH TABLE) ...), that is, each entry is a list with three elements.

     REGEXP.  Regular expression matching the macro we want to parse.

     MATCH.  A number or list of numbers, each representing one parenthesized subexpression matched by REGEXP.

     TABLE.  The symbol table to store the data.  This can be a function, in which case the function is called with the argument MATCH.  Use 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 MATCH is a number, a list of strings if MATCH is a list of numbers) is put in front of the table.

 -- Variable: TeX-auto-prepare-hooks nil
     List of hooks to be called before parsing a TeX file.

 -- Variable: TeX-auto-cleanup-hooks nil
     List of hooks to be called after parsing a TeX file.

Installation of AUC TeX
***********************

Before you do anything else, make sure that you have the latest version of TeXinfo installed.  It is available by ftp from prep.ai.mit.edu.  You need at least version 2.16.

First, you should consult the file tex-site.el and edit it to fit your local site.  Be sure to get the following two variables right, or you will not be able to complete the installation procedure:

 -- User Option: TeX-lisp-directory
     The directory where you want to install the AUC TeX lisp files.

 -- User Option: TeX-macro-global
     Directories containing the site's TeX style files.

You probably also need to change TeX-command-list to make sure that the commands used for starting TeX, printing, etc. work on your system.

Finally, edit TeX-printer-list to contain the printers available at your site.

Next, edit the file Makefile in the AUC TeX directory to set up paths for installation of the files.  Be sure that

bindir
     Is set to the directory where you want the LaCheck binary to be installed.

infodir
     Is set to the directory where you want the AUC TeX ``info'' documentation to be installed.

aucdir
     Is set to the directory where you want the lisp files for AUC TeX to be installed.  This must be the same directory as you specified for TeX-lisp-directory in tex-site.el.  If you unpacked AUC TeX in that directory (TeX-lisp-directory), you should set aucdir to . in order to avoid copying the byte compiled lisp files.

     If you already have an old version of AUC TeX in that directory, you must delete it before installing the new version.  Otherwise the wrong version of the files may be loaded during the byte compilation.

mandir
     Is set to the directory where you want to install the (unformatted) man page for LaCheck.

elispdir
     Is set to the directory where the lisp files from the standard Emacs distribution are found.

CC
     Is the compiler you want to use for compiling the LaCheck program. Is set to `gcc' by default. Change this is `cc' or whatever your system compiler is called if you do not have GCC installed.

Then type make all, and the whole thing will be `made'.  If this succeeds, type make install, and it will be installed.

To extract information from your site's TeX macros, type make install-auto. This will only work if you have set TeX-macro-global correctly in tex-site.el.

Tell the users on your site to insert

             (load-file "/path/for/auctex/tex-site.elc")

in their .emacs file in order to use AUC TeX.

Users who know the older keybindings from version 6.1 may also want to insert

             (load "auc-tex")

in their .emacs

The History of AUC TeX
**********************

This chapter is for old users, who want to see what has been added in this version, and for the authors, who get nostalgic at times.

News in 7.3
===========

Coordinater: Per Abrahamsen, 1993.

  * More robust installation, especially for Lucid Emacs (I hope).  Many people reported problems with this.

  * Make `easymenu' work when byte-compiled.  Many people reported this bug.

  * Minimally updated the README file from version 6.0 (sigh). Thanks to Boris Goldowsky <boris@cs.rochester.edu> for reporting this.

  * Added @finalout to manual.  Reported by Henrik Drabol <hvd@ens004.ens.min.dk>.

  * Fixed M-q to work after an \end{...}.  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 <koba@flab.fujitsu.co.jp> again.

  * New variables TeX-open-quote and TeX-close-quote determine what is inserted by TeX-insert-quote.  The german style file now use those variables instead of changing the keymap.

  * Changes to the default settings in tex-site.el, in particular a Queue command is added to display the print queue.  Thanks to John Interrante <interran@uluru.Stanford.EDU> for code, and other members of the auc-tex@iesd.auc.dk mailing list for ideas.

  * Make sure all outline mode commands are bound in outline-minor-mode.

  * Added autoload for TeX-command.  Thanks to Hanno Wirth <wirth@igd.fhg.de> for reporting this.

  * Added support for AmSTeX and AmSLaTeX.  Currently they are identical to TeX and LaTeX except for another default command.

  * Added VorTeX style matching of dollar sign.  The style is guaranteed to be VorTeX, since I lifted the code directly from VorTeX. Thanks to Pehong Chen <phc@renoir.berkeley.edu> for writing the VorTeX code.  Thanks to Jak Kirman <jak@cs.brown.edu> for pointing out this nice VorTeX feature.

  * Added information about AUC TeX mail addresses to the manual.  Thanks to Dave Smith <maa507@computing.lancaster.ac.uk>.

  * Added menu to for plain TeX.  Suggested by Tim Carlson <imsgtcar@sinc.oscs.montana.edu>.

  * Made the menus depend on TeX-command-list.

  * Made it possible to specify TeX-auto-regexp-list in the local variable section of each file.

  * Added variable TeX-auto-parse-length to specify maximal length of text that will be parsed.

  * Added automatic parsing of BibTeX files and bibitem entries in order to get completion in cite.  This was inspired by an add on made by Sridhar Anandakrishnan <sak@essc.psu.edu>.

  * Added variable TeX-byte-compile to disable automatic byte compilation of style files when loaded.  This is needed when using different Emacs versions.

  * Added variable TeX-translate-location-hook to translate file and line information before showing an error, as requested by Thorbjoern Ravn Andersen <ravn@imada.ou.dk>.

  * Added variable TeX-auto-save to allow disabling the automatic saving of style information, either per file in the file local variables, or globally by using setq-default.  Use TeX-normal-mode to force style information to be saved.

  * Try to create auto directory if it does not exists.

  * Added chapter describing how to tune the TeX parsing.

  * Allow (but do not encourage) a string value for LaTeX-default-options.

  * Give " word syntax when german.sty is loaded.  Suggested by Tim Geisler <tmgeisle@immd8.informatik.uni-erlangen.de>.

  * Many corrections to the grammar in the manual.  Thanks to Manfred Weichel <Manfred.Weichel@sto.mchp.sni.de>.

  * Bind TeX-home-buffer to C-c ^ instead of C-c C-h which are reserved in Emacs 19.  Suggested by Chris Moore <Chris.Moore@src.bae.co.uk>.

News in 7.2
===========

Coordinater: Per Abrahamsen, 1993.

  * LaTeX-dead-mode works again.  Thanks to Patrick O'Callaghan <poc@usb.ve> for fixing it.

  * Minor fixes to the documentation.  Thanks to Shinji Kobayashi <koba@flab.fujitsu.co.jp>.

  * Add Compiling to the mode line of all buffers, while there is a AUC TeX compilation process running.  This is similar to the behavior of compile in Emacs 19.

  * TeX-normal-mode will now save the buffer first to make sure it gets reparsed.

  * Labels with underscores are now recognized.   Thanks to Wolfgang Franzki <W.Franzki@kfa-juelich.de>

  * Fix to `ghostview' printer specification.  Thanks to Masayuki Kuwada <kuwada@soliton.ee.uec.ac.jp>.

  * Recognize abstract, center, titlepage, verse, and theindex environments.  Thanks to Masayuki Kuwada <kuwada@soliton.ee.uec.ac.jp>.

  * Fix to newsavebox macro.  Thanks to Shinji Kobayashi <koba@flab.fujitsu.co.jp> for reporting this.

  * Menu support for GNU Emacs 19 and Lucid Emacs.  Thanks to Alastair Burt <burt@dfki.uni-kl.de> for the initial Lucid Emacs version.

  * 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.

  * Giving C-c C-f a prefix argument will replace the current font, i.e. 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 C-w C-c C-f C-b C-y instead.

  * Chapter recognized as largest heading in the report style.  Thanks to Shinji Kobayashi <koba@flab.fujitsu.co.jp> for reporting this.

  * More support for Japanese style files.  Thanks to Shinji Kobayashi <koba@flab.fujitsu.co.jp>.

  * No longer put Outline in the mode line whenever selective-display is set.  Thanks to Lawrence R. Dodd <dodd@roebling.poly.edu> for reporting this.

  * Support for inserting calligraphic letters in TeX-math-mode with ` c LETTER.  Thanks to Olaf Burkart <burkart@zeus.informatik.rwth-aachen.de>.

  * set-docstring in tex-math.el should work better now. Thanks to Alastair Burt <burt@dfki.uni-kl.de> and Olaf Burkart <burkart@zeus.informatik.rwth-aachen.de>.

  * Support for dviout preview on PC-9801.  Thanks to Shinji Kobayashi <koba@flab.fujitsu.co.jp>.

  * Inserting environment in empty buffer should work now.  Thanks to Alastair Burt <burt@dfki.uni-kl.de>.

  * Default float for figures changed from tbp to htbp.

  * LaTeX-format-environment may work now.  Thanks to Shinji Kobayashi <koba@flab.fujitsu.co.jp>.

  * Better LaTeX-close-environment.  Thanks to Thorbjoern Hansen <thansen@diku.dk>.

  * Some support for Ispell 4.0.

  * BibTeX in Emacs 19 need tex-insert-quote, make it autoload from AUC TeX instead of the standard tex-mode.

  * TeX-auto-generate failed when repeated.  Thanks to Peter Whaite <peta@Thunder.McRCIM.McGill.EDU> for reporting this.

News in 7.1
===========

Coordinater: Per Abrahamsen, 1993.

  * Allow multiple %p in print commands.

     Suggested by Cliff Krumvieda <cliff@cs.cornell.edu>.

  * Improved backward compatibility in auc-tex.el.  Thanks to Ralf Handl <handl@cs.uni-sb.de>.

  * New style hook for german.sty.

     Disable smart quotes.  Press C-c C-n to make it take effect.

  * Allow files to have other extensions than ``tex''.

     But no longer allow files to have multiple dots.  Sigh.

  * Will no longer parse the buffer if it can use the saved state.

  * New variable TeX-parse-self.

     Set it to nil if you never want to parse the buffer when you load it.

  * Only offer to save files that belongs to the document.

     When you format the document with C-c C-c, AUC TeX will no longer offer to save your RMAIL, .newsrc, or other files that does not belong to the document.  Suggested by Jim Hetrick <hetrick@phys.uva.nl>.

  * FoilTeX support.

     Thanks to Sven Mattisson <sven@tde.lth.se>

  * Smarter about when you need to reformat.

     Thanks to Chris Callsen <chris@iesd.auc.dk>.

  * Japanese TeX

     Now supports Japanese TeX.  Thanks to Shinji Kobayashi <koba@keisu-s.t.u-tokyo.ac.jp>.

  * Works again under OS/2 and other case insensitive file systems.

  * DEMACS support.

     Thanks to Shinji Kobayashi <koba@keisu-s.t.u-tokyo.ac.jp>.

  * Better LaTeX-close-environment.

     Thanks to Piet van Oostrum <piet@cs.ruu.nl>.

  * Ispell support.

     Thanks to Piet van Oostrum <piet@cs.ruu.nl>.

  * Support for Russian letters.

     Thanks to Justin R. Smith <jsmith@king.mcs.drexel.edu>.

  * SliTeX fixes.

     Many people.

  * Fixes for spelling errors.

     Many people.

Version 7.0
===========

Coordinator: Per Abrahamsen, 1993.

Alpha testers (in order of appearance): Piet van Oostrum <piet@cs.ruu.nl>, Sven Mattisson <sven@tde.lth.se>, Tim Geisler <tmgeisle@immd8.informatik.uni-erlangen.de>, Fran E. Burstall <F.E.Burstall@maths.bath.ac.uk>, Alastair Burt <burt@dfki.uni-kl.de>, Sridhar Anandakrishnan <sak@essc.psu.edu>, Kjell Gustafsson <kjell@sccm.Stanford.EDU>, Uffe Kjaerulff <uk@iesd.auc.dk>, Kurt Swanson Kurt.Swanson@dna.lth.se, Mark Utting <marku@cs.uq.oz.au>, Per Norman Oma perno@itk.unit.no, Naji Mouawad <nmouawad@math.uwaterloo.ca>, Bo Nygaard Bai <bai@iesd.auc.dk>, and probably more.

  * 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 tex-init.el instead of auc-tex.el.

     The file auc-tex.el is still available and implements the old keybinding on top of the new code.

     Print out the reference card (doc/ref-card.tex) to see the new bindings.

  * Completely redesigned the buffer handling.

     No part of the interface or the customization variables remain the same, unless you use the compatibility functions in auc-tex.el.  In that case the interactive commands remain similar in spirit, but the customization interface is still changed.

     The file tex-buf.el has been completely rewritten, and there are major cleanup in tex-dbg.el, however the basic functionality remains the same in this file.  The code for both tex-buf.el and tex-dbg.el should be much simpler now and easier to extent.

     auc-tex.el and tex-site.el was updated to support the new interface.  I actually believe the moral equivalent to TeX-region to work now :-), at least I understand the code now.

     The two major functions are now TeX-command-master and 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 TeX-command-list.

     TeX-command-master will run the specified command on the buffers master file.  You can have one command running for each master file. 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 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 TeX-add-local to nil.  Furthermore, it will convert %% Master: lines to file variables, unless you disable it by setting TeX-convert-master to nil.

     Functionality removed (for now, it might appear again latter) include all other functions to start a command (e.g. 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).

  * 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.

  * Automatically generate style files.

     AUC TeX can now automatically extract information from a TeX file, and will do this when you save a buffer.

  * SliTeX mode.

     Just like LaTeX mode, except that the default command to format run on the buffer is slitex.

  * LaTeX-section completely general.

     Rewrote ltx-sec.el.

       - Sectioning level, toc, and title queries can be individually turned off.

       - Label query can be turned on or off for selected sectioning levels.

       - Label prefix can be different for different sectioning levels.

       - If the title (or toc) is empty, point will be positioned there.

       - Users can add new hooks

  * 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.

  * Fixed center in figure environment.

     Thanks to Thomas Koenig <ig25@rz.uni-karlsruhe.de>.

  * Changed \M- to \e in all keybindings in order to better support 8-bit input on some GNU Emacs. Thanks to Peter Dalgaard <pd@kubism.ku.dk>.

     Please, implementors of 8-bit input extensions to GNU Emacs. \M-x does not means x with the 8-bit set.  It means pressing x while holding down the META key. Some systems (such as X11) are able to tell the different.  Thus, even if you implement 256 byte keymaps, \M-x should still expand meta-prefix-char followed by an x in the keymap.  This allows you to distinguish pressing x while holding down the META key from entering a literal 8-bit character.

  * Made the outline commands aware of the document style.

     That is, if the document style is article, \section will be one level below the \documentstyle, while if the style is book, \section will be three levels below \documentstyle.  This will make show-children work better at the top level.

  * The makefiles are closer to GNU coding standard.

     They now understand `prefix' and some other macros.

  * 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 <piet@cs.ruu.nl>.

  * Added * to lot of (interactive) declarations.

  * The outline commands are now always accessible from LaTeX mode.

  * Generalized the keyboard remapping and double modes.

     These are found in the file min-key.el.

  * 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.

  * Add outline headers.

     It is now possible to add extra outline headers, by setting the variable TeX-outline-extra.

  * Smart quotes even smarter.

     If you press " twice, it will insert an real double quote instead of two (or four) single quotes.  This is consistent with how remapping in min-key.el is done.

  * 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.

  * Call show-all when you change major mode.

     Thanks to Inge Frick's <inge@nada.kth.se> 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.

  * 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 (see Multifile).

Version 6.1
===========

Coordinator: Per Abrahamsen, 1992.

  * TeX-region might work now (heard that before?).

     Many people reported this one.  Especially thanks to Fran Burstall <F.E.Burstall@maths.bath.ac.uk> and Bill Schworm <bill@schworm.econ.ubc.ca>.

  * The specification format for the TeX command is more general.

     See the documentation for LaTeX-command and plain-TeX-command.

  * The specification format for the preview commands is more general.

     See their respective documentation.

  * The specification format for the print command is more general.

     See the documentation for TeX-print-command.

  * TeX-args is marked as obsolete.

  * The "Emergency stop ..." error.

     Some users of old TeX installations got might might be fixed now. Thanks to Philip Sterne <sterne@dublin.llnl.gov>.

  * It is now possible to change the preview command.

     ... without loading TeX-site first.  Thanks to Tim Bradshaw <tim.bradshaw@edinburgh.ac.uk>.

  * New variable TeX-smart-quotes.

     Allow german.sty users (and others) to disable the mapping of double quote (" to `` or '').  Thanks to Daniel Hernandez <danher@informatik.tu-muenchen.de>.

  * Many minor corrections to the documentation.

     Thanks to Mainhard E.  Mayer <hardy@golem.ps.uci.edu>.

  * Make test for HOSTTYPE case insensitive.

     Thanks to Gisli Ottarsson <gisli@liapunov.eecs.umisc.edu>.

  * TeX-force-default-mode

     Set to avoid AUC TeX's attempts to infer the mode of the file by itself.

Version 6.0
===========

Coordinator: Kresten Krab Thorup, 1992.

Preliminary documentation is available in the directory 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...

LaCheck has been incorporated in the package.  The source code for it is available in the directory lacheck along with the documentation for it.  Lacheck may also be used from the command line.  It is bound to C-c $.

Some minor changes in:

TeX-region
     Should work better with Master: option.

LaTeX-environment
     Numerous new hooks added by Masayuki Kuwada.

TeX-command-on-region
     Removed. C-c C-o used for outline-minor-mode instead.

And some additional minor fixes...

Ancient History
===============

The origin of AUC TeX is tex-mode.el from Emacs 16.  Lars Peter Fischer <fischer@iesd.auc.dk> wrote the first functions to insert font macros and Danish characters back in 1986.  Per Abrahamsen <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 <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 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.

<dduchier@csi.UOttawa.CA>
     Denys Duchier

<ferguson@cs.rochester.edu>
     George Ferguson

<simons@ibiza.karlsruhe.gmd.de>
     Martin Simons

<smith@pell.anu.edu.au>
     Michael Smith

<per@iesd.auc.dk>
     Per Hagen

<handl@cs.uni-sb.de>
     Ralf Handl

<sven@tde.lth.se>
     Sven Mattisson

<kuwada@soliton.ee.uec.ac.jp>
     Masayuki Kuwada

<tb06@pl118f.cc.lehigh.edu>
     Terrence Brannon

<roseman@hustat.harvard.edu>
     Leonard Roseman

Special thanks to Leslie Lamport for supplying the source for the LaTeX error messages in the tex-dbg.el file.

Various Minor Modes
*******************

A number of minor modes are distributed with AUC TeX for no good reason, except that they use min-bind.el and they are so small that it does not matter.

Some of the minor modes have already been described elsewhere, the remaining will be described here.

Auto Indent Mode
================

This is a minor mode version of indented-text-mode. Enter and leave with M-x auto-indent-mode.

 -- Command: auto-indent-mode
     Toggle auto indent mode. With prefix arg, turn auto indent mode on iff arg is positive.

     Auto indent mode works by invoking indent-relative for TAB, and using indent-relative-maybe as the indent-line-function for auto-fill, and LFD.

Auto Ispell Mode
================

In auto-ispell-mode SPC or RET automatically trigger ispell-word on previously typed word.  M-TAB will make an ispell completion.

Enter and leave with M-x auto-ispell-mode.

 -- Command: auto-ispell-mode
     (M-x auto-ispell-mode) Toggle auto-ispell-mode. With prefix arg, turn auto-ispell-mode on iff arg is positive.

     In auto-ispell-mode, inserting a space or a newline applies ispell-word on the previous word.

     Pressing Esc-Tab activates ispell-complete-word.

Currently supported symbols in LaTeX-math-mode
**********************************************

` ?
     Help, list of math symbols.

` a
     \alpha

` b
     \beta

` d
     \delta

` e
     \epsilon

` f
     \phi

` g
     \gamma

` h
     \eta

` k
     \kappa

` l
     \lambda

` m
     \mu

` n
     \nu

` o
     \omega

` p
     \pi

` q
     \theta

` r
     \rho

` s
     \sigma

` t
     \tau

` u
     \upsilon

` x
     \chi

` y
     \psi

` z
     \zeta

` D
     \Delta

` G
     \Gamma

` Q
     \Theta

` L
     \Lambda

` Y
     \Psi

` P
     \Pi

` S
     \Sigma

` U
     \Upsilon

` V
     \Phi

` O
     \Omega

` C-f
     \rightarrow

` C-b
     \leftarrow

` C-p
     \uparrow

` C-n
     \downarrow

` <
     \leq

` >
     \geq

` ~
     \tilde

` I
     \infty

` A
     \forall

` E
     \exists

` !
     \not

` i
     \in

` *
     \times

` .
     \cdot

` {
     \subset

` }
     \supset

` [
     \subseteq

` ]
     \supseteq

` \
     \backslash

` /
     \setminus

` +
     \cup

` -
     \cap

` (
     \langle

` )
     \rangle

` C-e
     \exp

` C-s
     \sin

` C-c
     \cos

` C-^
     \sup

` C-_
     \inf

` C-d
     \det

` C-l
     \lim

` C-t
     \tan

` ^
     \hat

` v
     \vee

Wishlist
********

This is a list of projects for AUC TeX.  Bug reports and requests we can not fix or honor right away will be added to this list.  If you have some time for emacs lisp hacking, you are encouraged to try to provide a solution to one of the following problems.

  * Add completion of macro arguments to TeX-complete-symbol.

  * Make . check for abbreviations and sentences ending with capital letters.  Make , and . remove italic correction.

  * Make LaCheck check for itallic correction before . or ,.

  * Use Emacs 19 minubuffer history to choose between previewers, and other stuff.  Suggested by John Interrante <interran@uluru.Stanford.EDU>.

  * It is often too slow to parse the file each time it is saved, especially with Emacs 19.  Check if TeX-auto-generate is useful for doing more occasionally, like updating the TAGS file.

  * Control TeX compilation window.

     It is not good that half of the screen is wasted for the log when TeX is processing a file. It is possible to make the log screen smaller, but the best solution would be to have a user configurable window layout that could be defined by some variables as for VM or GNUS. Or a log screen that opens only in case of an error. --- Tim Geisler <tmgeisle@immd8.informatik.uni-erlangen.de>

  * Make features.

     A new command TeX-update (C-c C-u) could be used to create an up to date dvi file by repeatedly running BibTeX, MakeIndex and (La)TeX, until an error occur or we are done.

     An alternative is to have an Update command that ensures the dvi file is up to date.  This could be called before printing and previewing.

  * Hook naming should be accoriding to the Emacs (19) guidelines. Specifically, only the hook variable should be names -hook. The hook functions should have other names.

  * The documentation of the minor modes should be separated.

     They are distributed independently of AUC TeX, and should therefore also be documented independently of AUC TeX.

  * 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 AUC TeX depends on, unless AUC TeX knows that it has to run the style hooks first.

     Here is the start of such a list.

     LaTeX-add-environments

     TeX-add-symbols

     LaTeX-add-labels

     LaTeX-add-bibliographies

     LaTeX-largest-level

     The rules for what can be done in a format package hook are different.

  * Correct indentation for table, math, and array environments.

  * Customizable indentation for verbatim-like user defined environments.

  * Special indentation after an \item.

          \begin{itemize}
          \item blabalaskdfjlas lajf adf
                lkfjl  af jasl lkf jlsdf jlf
          \item f lk jldjf lajflkas flf af
          \end{itemize}

  * Completion for citations, counters, and sboxes.

     The two latter is easy the first is useful.

  * Outline should be able to hide environments.

     Probably being one level below LaTeX-lowest-level.

  * Outline should be (better) supported in TeX mode.

     At least, support headers, trailers, as well as TeX-outline-extra.

  * Outline Minor Mode should support non-regexp outlines better.

     Something like TeX-outline-extra should be standard support in min-out.el.

  * TeX-header-start and TeX-trailer-end.

     We might want these, just for fun (and outlines)

  * 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.

  * Add support for original TeX-mode keybindings.

     A third initialization file (tex-mode.el) containing an emulator of the standard TeX-mode would help convince some people to change to AUC TeX.

  * Make TeX-next-error parse ahead and store the results in a list, using markers to remember buffer positions in order to be more robust with regard to line numbers and changed files.  This is what next-error does. (Or did, until Emacs 19).

  * When LaTeX-environment is given an argument, change the current environment.  Be smart about \item[] versus \item  and labels like fig: versus tab:.

  * Check out if lightening completion from Ultra TeX is anything for us.

  * TeXinfo mode.

  * BibTeX mode.

  * Support for AMSLaTeX style files.

  * Better LaTeX letter environment.

     Make a database system for addresses in the letter environment Make the letter environment hook produce `documentstyle' too

  * Add code for submitting a report, using BAW's reporter.el.

Credit
******

A big smile and thanks should go to all the folks who cheered me up, during the long hours of programming... sorry folks, but I can't help including the list below, of comments I've got...

Kresten Krab Thorup

<monheit@psych.stanford.edu>
     I'd like to say that I'm very much enjoying using auc-tex.  Thanks for the great package!

<georgiou@rex.cs.tulane.edu>
     I really enjoy working with auc-tex.

<toy@soho.crd.ge.com>
     Thanks for your great package.  It's indispensable now!  Thanks!

<ascott@gara.une.oz.au>
     Thanks for your time and for what appears to be a great and useful package.  Thanks again

<hal@alfred.econ.lsa.umich.edu>
     Thanks for providing auc-tex.

<simons@ibiza.karlsruhe.gmd.de>
     I really enjoy using the new emacs TeX-mode you wrote.  I think you did a great job.

<clipper@csd.uwo.ca>
     I am having fun with auc-tex already.

<ibekhaus@athena.mit.edu>
     Thanks for your work on auc-tex, especially the math-minor mode.

<burt@dfki.uni-kl.de>
     I like your auc-tex elisp package for writing LaTeX files - I am especially impressed by the help with error correction.

<goncal@cnmvax.uab.es>
     Thanks so much!

<bond@sce.carleton.ca>
     I >really< like the macro, particularly the hooks for previewing and the error parsing!

<ascott@gara.une.oz.au>
     All in all I am pleased with your package.  Thanks a lot.