2.4.1 Equations

When inserting equation-like environments, the ‘\label’ will have a default prefix, which is controlled by the following variables:

User Option: LaTeX-equation-label ¶

Prefix to use for ‘equation’ labels.

User Option: LaTeX-eqnarray-label ¶

Prefix to use for ‘eqnarray’ labels.

User Option: LaTeX-amsmath-label ¶

Prefix to use for amsmath equation labels. Amsmath equations include ‘align’, ‘alignat’, ‘xalignat’, ‘multline’, ‘flalign’ and ‘gather’.

2.4.2 Floats

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

float position

This is the optional argument of float environments that controls how they are placed in the final document. In LaTeX this is a sequence of the letters ‘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. The default is to insert the caption at the bottom of the float. You can specify floats where the caption should be placed at the top with LaTeX-top-caption-list.

short caption

If the specified caption is greater than a specific length, then a short caption is prompted for and it is inserted as an optional argument to the ‘\caption’ macro. The length that a caption needs to be before prompting for a short version is controlled by LaTeX-short-caption-prompt-length.

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, you will be asked if you want the contents of the float environment to be horizontally centered. Upon a positive answer a ‘\centering’ macro will be inserted at the beginning of the float environment.

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.

User Option: LaTeX-top-caption-list ¶

List of float environments with top caption.

User Option: LaTeX-short-caption-prompt-length ¶

Number of chars a caption should be before prompting for a short caption.

2.4.3 Itemize-like Environments

In an itemize-like environment, nodes (i.e., ‘\item’s) may be inserted using C-c LFD or M-RET. The latter is only defined as an alias if the key binding is still available.

Command: LaTeX-insert-item ¶

(C-c LFD or M-RET) 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.

User Option: TeX-arg-item-label-p ¶

If non-nil, you will always be asked for optional label in items. Otherwise, you will be asked only in description environments.

2.4.4 Tabular-like Environments

When inserting Tabular-like environments, that is, ‘tabular’ ‘array’ etc., you will be prompted for a template for that environment. Related variables:

User Option: LaTeX-default-format ¶

Default format string for array and tabular environments.

User Option: LaTeX-default-width ¶

Default width for minipage and tabular* environments.

User Option: LaTeX-default-position ¶

Default position string for array and tabular environments. If nil, act like the empty string is given, but don’t prompt for a position.

AUCTeX calculates the number of columns from the format string and inserts the suitable number of ampersands.

You can use C-c LFD or M-RET (LaTeX-insert-item) to terminate rows in these environments. It supplies line break macro ‘\\’ and inserts the suitable number of ampersands on the next line. AUCTeX also supports the ‘*{num}{cols}’ notation (which may contain another ‘*’-expression) in the format string when calculating the number of ampersands. Please note that ‘num’ and ‘cols’ must be enclosed in braces; expressions like ‘*2l’ are not recognized correctly by the algorithm.

Command: LaTeX-insert-item ¶

(C-c LFD or M-RET) Close the current row with ‘\\’, move to the next line and insert an appropriate number of ampersands for the current environment.

Similar supports are provided for various amsmath environments such as ‘align’, ‘gather’, ‘alignat’, ‘matrix’ etc. Try typing C-c LFD or M-RET in these environments. It recognizes the current environment and does the appropriate job depending on the context.

2.4.5 Customizing Environments

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

2.7.1 LaTeX Commands for Marking Environments and Sections

Command: LaTeX-mark-section ¶

(C-c *) Set mark at end of current logical section, and point at top.

With a non-nil prefix argument, mark only the region from the current section start to the next sectioning command. Thereby subsections are not being marked. Otherwise, any included subsections are also marked along with current section.

Command: LaTeX-mark-environment ¶

(C-c .) Set mark to the end of the current environment and point to the matching beginning.

If a prefix argument is given, mark the respective number of enclosing environments. The command will not work properly if there are unbalanced begin-end pairs in comments and verbatim environments.

2.7.2 Texinfo Commands for Marking Environments and Sections

Command: Texinfo-mark-section ¶

(C-c *) Mark the current section, with inclusion of any containing node.

The current section is detected as starting by any of the structuring commands matched by the regular expression in the variable outline-regexp which in turn is a regular expression matching any element of the variable texinfo-section-list.

With a non-nil prefix argument, mark only the region from the current section start to the next sectioning command. Thereby subsections are not being marked. Otherwise, any included subsections are also marked.

Note that when the current section is starting immediately after a node command, then the node command is also marked as part of the section.

Command: Texinfo-mark-environment ¶

(C-c .) Set mark to the end of the current environment and point to the matching beginning.

If a prefix argument is given, mark the respective number of enclosing environments. The command will not work properly if there are unbalanced begin-end pairs in comments and verbatim environments.

Command: Texinfo-mark-node ¶

(C-M-h) Mark the current node. This is the node in which point is located. It is starting at the previous occurrence of the keyword @node and ending at next occurrence of the keywords @node or @bye.

3.1.1 Fontification of macros

Highlighting of macros can be customized by adapting keyword lists which can be found in the customization group font-latex-keywords.

Three types of macros can be handled differently with respect to fontification:

1. Commands of the form ‘\foo[bar]{baz}’ which consist of the macro itself, optional arguments in square brackets and mandatory arguments in curly braces. For the command itself the face font-lock-keyword-face will be used and for the optional arguments the face font-lock-variable-name-face. The face applied to the mandatory argument depends on the macro class represented by the respective built-in variables.
2. Declaration macros of the form ‘{\foo text}’ which consist of the macro which may be enclosed in a TeX group together with text to be affected by the macro. In case a TeX group is present, the macro will get the face font-lock-keyword-face and the text will get the face configured for the respective macro class. If no TeX group is present, the latter face will be applied to the macro itself.
3. Simple macros of the form ‘\foo’ which do not have any arguments or groupings. The respective face will be applied to the macro itself.

Customization variables for ‘\foo[bar]{baz}’ type macros allow both the macro name and the sequence of arguments to be specified. The latter is done with a string which can contain the characters

‘*’

indicating the existence of a starred variant for the macro,

‘[’

for optional arguments in brackets,

‘{’

for mandatory arguments in braces,

‘\’

for mandatory arguments consisting of a single macro and

‘|’

as a prefix indicating that two alternatives are following.

For example the specifier for ‘\documentclass’ would be ‘[{’ because the macro has one optional followed by one mandatory argument. The specifier for ‘\newcommand’ would be ‘*|{\[[{’ because there is a starred variant, the mandatory argument following the macro name can be a macro or a TeX group which can be followed by two optional arguments and the last token is a mandatory argument in braces.

Customization variables for the ‘{\foo text}’ and ‘\foo’ types are simple lists of strings where each entry is a macro name (without the leading backslash).

General macro classes

font-latex provides keyword lists for different macro classes which are described in the following table:

font-latex-match-function-keywords

Keywords for macros defining or related to functions, like ‘\newcommand’.
Type: ‘\macro[...]{...}’
Face: font-lock-function-name-face

font-latex-match-reference-keywords

Keywords for macros defining or related to references, like ‘\ref’.
Type: ‘\macro[...]{...}’
Face: font-lock-constant-face

font-latex-match-textual-keywords

Keywords for macros specifying textual content, like ‘\caption’.
Type: ‘\macro[...]{...}’
Face: font-lock-type-face

font-latex-match-variable-keywords

Keywords for macros defining or related to variables, like ‘\setlength’.
Type: ‘\macro[...]{...}’
Face: font-lock-variable-name-face

font-latex-match-warning-keywords

Keywords for important macros, e.g. affecting line or page break, like ‘\clearpage’.
Type: ‘\macro’
Face: font-latex-warning-face

Sectioning commands

Sectioning commands are macros like ‘\chapter’ or ‘\section’. For these commands there are two fontification schemes which may be selected by customizing the variable font-latex-fontify-sectioning.

User Option: font-latex-fontify-sectioning ¶

Per default sectioning commands will be shown in a larger, proportional font, which corresponds to a number for this variable. The font size varies with the sectioning level, e.g. ‘\part’ (font-latex-sectioning-0-face) has a larger font than ‘\paragraph’ (font-latex-sectioning-5-face). Typically, values from 1.05 to 1.3 for font-latex-fontify-sectioning give best results, depending on your font setup. If you rather like to use the base font and a different color, set the variable to the symbol ‘color’. In this case the face font-lock-type-face will be used to fontify the argument of the sectioning commands.

You can make font-latex aware of your own sectioning commands be adding them to the keyword lists: font-latex-match-sectioning-0-keywords (font-latex-sectioning-0-face) … font-latex-match-sectioning-5-keywords (font-latex-sectioning-5-face).

Related to sectioning there is special support for slide titles which may be fontified with the face font-latex-slide-title-face. You can add macros which should appear in this face by customizing the variable font-latex-match-slide-title-keywords.

Commands for changing fonts

LaTeX provides various macros for changing fonts or font attributes. For example, you can select an italic font with ‘\textit{...}’ or bold with ‘\textbf{...}’. An alternative way to specify these fonts is to use special macros in TeX groups, like ‘{\itshape ...}’ for italics and ‘{\bfseries ...}’ for bold. As mentioned above, we call the former variants commands and the latter declarations.

Besides the macros for changing fonts provided by LaTeX there is an infinite number of other macros—either defined by yourself for logical markup or defined by macro packages—which affect the font in the typeset text. While LaTeX’s built-in macros and macros of packages known by AUCTeX are already handled by font-latex, different keyword lists per type style and macro type are provided for entering your own macros which are listed in the table below.

font-latex-match-bold-command-keywords

Keywords for commands specifying a bold type style.
Face: font-latex-bold-face

font-latex-match-italic-command-keywords

Keywords for commands specifying an italic font.
Face: font-latex-italic-face

font-latex-match-underline-command-keywords

Keywords for commands specifying an underlined text.
Face: font-latex-underline-face

font-latex-match-math-command-keywords

Keywords for commands specifying a math font.
Face: font-latex-math-face

font-latex-match-type-command-keywords

Keywords for commands specifying a typewriter font.
Face: font-lock-type-face

font-latex-match-bold-declaration-keywords

Keywords for declarations specifying a bold type style.
Face: font-latex-bold-face

font-latex-match-italic-declaration-keywords

Keywords for declarations specifying an italic font.
Face: font-latex-italic-face

font-latex-match-type-declaration-keywords

Keywords for declarations specifying a typewriter font.
Face: font-latex-type-face

Deactivating defaults of built-in keyword classes

font-latex ships with predefined lists of keywords for the classes described above. You can disable these defaults per class by customizing the variable font-latex-deactivated-keyword-classes. This is a list of strings for keyword classes to be deactivated. Valid entries are "warning", "variable", "biblatexnoarg", "biblatex", "reference", "function", "function-noarg", "sectioning-0", "sectioning-1", "sectioning-2", "sectioning-3", "sectioning-4", "sectioning-5", "slide-title", "textual", "bold-command", "italic-command", "underline-command", "math-command", "type-command", "bold-declaration", "italic-declaration" or "type-declaration".

You can also get rid of certain keywords only. For example if you want to remove highlighting of footnotes as references you can put the following stanza into your init file:

(eval-after-load "font-latex"
  '(setq-default
    font-latex-match-reference-keywords-local
    (remove (assoc-string "footnote"
            font-latex-match-reference-keywords-local)
                font-latex-match-reference-keywords-local)))

But note that this means fiddling with font-latex’s internals and is not guaranteed to work in future versions of font-latex.

User-defined keyword classes

In case the customization options explained above do not suffice for your needs, you can specify your own keyword classes by customizing the variable font-latex-user-keyword-classes.

User Option: font-latex-user-keyword-classes ¶

Every keyword class consists of four parts, a name, a list of keywords, a face and a specifier for the type of macros to be highlighted.

When adding new entries, you have to use unique values for the class names, i.e. they must not clash with names of the built-in keyword classes or other names given by you. Additionally the names must not contain spaces.

The list of keywords defines which commands and declarations should be covered by the keyword class. A keyword can either be a simple command name omitting the leading backslash or a list consisting of the command name and a string specifying the sequence of arguments for the command.

The face argument can either be an existing face or face attributes made by you.

There are three alternatives for the type of keywords—“Command with arguments”, “Declaration inside TeX group” and “Command without arguments”—which correspond with the macro types explained above.

3.1.2 Fontification of quotes

Text in quotation marks is displayed with the face font-latex-string-face. Besides the various forms of opening and closing double and single quotation marks, so-called guillemets (<<, >>) can be used for quoting. Because there are two styles of using them—French style: << text >>; German style: >>text<<—you can customize the variable font-latex-quotes to tell font-latex which type you are using if the correct value cannot be derived from document properties.

User Option: font-latex-quotes ¶

The default value of font-latex-quotes is ‘auto’ which means that font-latex will try to derive the correct type of quotation mark matching from document properties like the language option supplied to the babel LaTeX package.

If the automatic detection fails for you and you mostly use one specific style you can set it to a specific language-dependent value as well. Set the value to ‘german’ if you are using >>German quotes<< and to ‘french’ if you are using << French quotes >>. font-latex will recognize the different ways these quotes can be given in your source code, i.e. (‘"<’, ‘">’), (‘<<’, ‘>>’) and the respective 8-bit variants.

If you set font-latex-quotes to nil, quoted content will not be fontified.

3.1.3 Fontification of mathematical constructs

In LaTeX mathematics can be indicated by a variety of different methods: toggles (like dollar signs), macros and environments. Math constructs known by font-latex are displayed with the face font-latex-math-face. Support for dollar signs and shorthands like ‘\(...\)’ or ‘\[...\]’ is built-in and not customizable. Support for other math macros and environments can be adapted by customizing the variables font-latex-match-math-command-keywords and texmathp-tex-commands respectively. It is no longer recommended to customize font-latex-math-environments.

To convert your customization in font-latex-math-environments into texmathp-tex-commands, please register your own math environments, together with starred variants if any, as entries of env-on type in texmathp-tex-commands, then clear out font-latex-math-environments. You have to restart Emacs for this new customization to take effect for fontification.

In order to make math constructs more readable, font-latex displays subscript and superscript parts in a smaller font and raised or lowered respectively. This fontification feature can be controlled with the variables font-latex-fontify-script and font-latex-script-display.

User Option: font-latex-fontify-script ¶

If non-nil, fontify subscript and superscript strings. Concretely, this means that the scripts are raised or lowered.

Another possiblity is setting this variable to the symbol multi-level. In this case, in a formula x^{y^z}, y is raised above and smaller than x, and z is raised above and smaller than y. With many script levels, the text might become too small to be readable. (See font-latex-fontify-script-max-level below.)

Lastly, you can set this variable to invisible whose behavior is like multi-level, and in addition the super-/subscript characters ^ and _ are not displayed.

User Option: font-latex-fontify-script-max-level ¶

Maximum scriptification level for which script faces are applied.

The faces font-latex-superscript-face and font-latex-subscript-face define custom :height values < 1.0. Therefore, scripts are displayed with a slightly smaller font than normal math text. If font-latex-fontify-script is multi-level or invisible, the font size becomes too small to be readable after a few levels. This option allows to specify the maximum level after which the size of the script text won’t be shrunken anymore.

For example, in the expression x^{y^{z^a_b}}, x has scriptification level 0, y has level 1, z has level 2, and both a and b have scriptification level 3.

If font-latex-fontify-script-max-level was 2, then z, a, and b would have the same font size. If it was 3 or more, then a and b were smaller than z just in the same way as z is smaller than y and y is smaller than x.

The script characters ‘^’ and ‘_’ themselves are also fontified with an own face named font-latex-script-char-face.

User Option: font-latex-script-display ¶

Display specification for subscript and superscript content. The car is used for subscript, the cdr is used for superscript. The feature is implemented using so-called display properties. For information on what exactly to specify for the values, see Other Display Specifications in GNU Emacs Lisp Reference Manual.

3.1.4 Verbatim macros and environments

Usually it is not desirable to have content to be typeset verbatim highlighted according to LaTeX syntax. Therefore this content will be fontified uniformly with the face font-latex-verbatim-face.

font-latex differentiates three different types of verbatim constructs for fontification. Macros with special characters like | as delimiters, macros with braces, and environments. Which macros and environments are recognized is controlled by the variables LaTeX-verbatim-macros-with-delims, LaTeX-verbatim-macros-with-braces, and LaTeX-verbatim-environments respectively.

3.1.5 Faces used by font-latex

In case you want to change the colors and fonts used by font-latex please refer to the faces mentioned in the explanations above and use M-x customize-face RET <face> RET. All faces defined by font-latex are accessible through a customization group by typing M-x customize-group RET font-latex-highlighting-faces RET.

3.1.6 Known fontification problems

In certain cases the fontification machinery fails to interpret buffer contents correctly. This can lead to color bleed, i.e. large parts of a buffer get fontified with an inappropriate face. A typical situation for this to happen is the use of a dollar sign (‘$’) in a verbatim macro or environment. If font-latex is not aware of the verbatim construct, it assumes the dollar sign to be a toggle for mathematics and fontifies the following buffer content with the respective face until it finds a closing dollar sign or till the end of the buffer.

As a remedy you can make the verbatim construct known to font-latex (see Verbatim macros and environments). If this is not possible, you can insert a commented dollar sign (‘%$’) at the next suitable end of line as a quick workaround. In docTeX documents, ‘^^A$’ is also available for similar purpose.

4.1.1 Starting a Command on a Document or Region

There are two ways to run an external command, you can either run it on the current document with TeX-command-master, or on the current region with TeX-command-region. A special case of running TeX on a region is TeX-command-buffer which differs from TeX-command-master if the current buffer is not its own master file.

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.

Command: TeX-command-region ¶

(C-c C-r) Query the user for a command, and run it on the contents of the selected region. The region contents are written into the region file, after extracting the header and trailer from the master file. If mark is inactive (which can happen with Transient Mark mode), use the old region. See also the command TeX-pin-region about how to fix a region.

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.

Command: TeX-command-buffer ¶

(C-c C-b) Query the user for a command, and apply it to the contents of the current buffer. The buffer contents are written into the region file, after extracting the header and trailer from the master file. The command is then actually run on the region file. See above for details.

Command: LaTeX-command-section ¶

(C-c C-z) Query the user for a command, and apply it to the current section (or part, chapter, subsection, paragraph, or subparagraph). What makes the current section is determined by LaTeX-command-section-level which can be enlarged/shrunken using LaTeX-command-section-change-level (C-c M-z). The given numeric prefix arg is added to the current value of LaTeX-command-section-level. By default, LaTeX-command-section-level is initialized with the current document’s LaTeX-largest-level. The buffer contents are written into the region file, after extracting the header and trailer from the master file. The command is then actually run on the region file. See TeX-command-region for details.

It is also possible to compile automatically the whole document until it is ready with a single command: TeX-command-run-all.

Command: TeX-command-run-all ¶

(C-c C-a) Compile the current document until an error occurs or it is finished. If compilation finishes successfully, run the viewer at the end.

Here are some relevant variables.

User Option: TeX-region ¶

The name of the file for temporarily storing the text when formatting the current region.

User Option: TeX-kill-process-without-query ¶

This boolean option controls whether AUCTeX should ask user before aborting a running process for a TeX document. It can be set as a file-local variable.

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 plain 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 plain TeX mode.

If you want to change the values of TeX-header-end and TeX-trailer-start you can do this for all files by setting the variables in a mode hook or per file by specifying them as file variables (see File Variables in The Emacs Editor).

Command: TeX-pin-region ¶

(C-c C-t C-r) If you don’t have a mode like Transient Mark mode active, where marks get disabled automatically, the region would need to get properly set before each call to TeX-command-region. If you fix the current region with C-c C-t C-r, then it will get used for more commands even though mark and point may change. An explicitly activated mark, however, will always define a new region when calling TeX-command-region.

If the last process you started was on the region, the commands described in Catching the errors and Controlling the output will work on that process, otherwise they will work on the process associated with the current document.

Don’t run more than one process at the same time. AUCTeX doesn’t support simultaneous typeset including region typeset. Wait for the previous process to finish before you start a new process, in particular when you are editing multiple documents in parallel. This limitation applies for preview by preview-latex as well.

4.1.2 Selecting and Executing a Command

Once you started the command selection with C-c C-c, C-c C-r or C-c C-b you will be prompted for the type of command. AUCTeX will try to guess which command is appropriate in the given situation and propose it as default. Usually this is a processor like ‘TeX’ or ‘LaTeX’ if the document was changed or a viewer if the document was just typeset. Other commands can be selected in the minibuffer with completion support by typing TAB.

The available commands are defined by the variable TeX-command-list. Per default it includes commands for typesetting the document (e.g. ‘LaTeX’), for viewing the output (‘View’), for printing (‘Print’), for generating an index (‘Index’) or for spell checking (‘Spell’) to name but a few. You can also add your own commands by adding entries to TeX-command-list. Refer to its doc string for information about its syntax. You might also want to look at TeX-expand-list to learn about the expanders you can use in TeX-command-list.

Note that the default of the variable occasionally changes. Therefore it is advisable to add to the list rather than overwriting it. You can do this with a call to add-to-list in your init file. For example, if you wanted to add a command for running a program called ‘foo’ on the master or region file, you could do this with the following form.

(eval-after-load "tex"
  '(add-to-list 'TeX-command-list
                '("Foo" "foo %s" TeX-run-command t t :help "Run foo")
                t))

As mentioned before, AUCTeX will try to guess what command you want to invoke. If you want to use another command than ‘TeX’, ‘LaTeX’ or whatever processor AUCTeX thinks is appropriate for the current mode, set the variable TeX-command-default. You can do this for all files by setting it in a mode hook or per file by specifying it as a file variable (see File Variables in The Emacs Editor).

User Option: TeX-command-default ¶

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

In case you use biblatex in a document, when automatic parsing is enabled AUCTeX checks the value of ‘backend’ option given to biblatex at load time to decide whether to use BibTeX or Biber for bibliography processing. Should AUCTeX fail to detect the right backend, you can use the file local LaTeX-biblatex-use-Biber variable.

Variable: LaTeX-biblatex-use-Biber ¶

If this boolean variable is set as file local, it tells to AUCTeX whether to use Biber with biblatex. In this case, the autodetection of the biblatex backend will be overridden. You may want to set locally this variable if automatic parsing is not enabled.

After confirming a command to execute, AUCTeX will try to save any buffers related to the document, and check if the document needs to be reformatted. If the variable TeX-save-query is non-nil, AUCTeX will query before saving each file. By default AUCTeX will check emacs buffers associated with files in the current directory, in one of the TeX-macro-private directories, and in the TeX-macro-global directories. You can change this by setting the variable TeX-check-path.

User Option: TeX-check-path ¶

Directory path to search for dependencies.

If nil, just check the current file. Used when checking if any files have changed.

When performing spell checking on a document or a region (invoked through AUCTeX’s ‘Spell’ command or M-x ispell RET), you want the spell checking program to skip certain macro arguments and environments, most notably the arguments of referencing macros and the contents of verbatim environments. The skipped parts are controlled by variable ispell-tex-skip-alists provided by ispell.el. AUCTeX has a library which can be added to this variable depending on the value of TeX-ispell-extend-skip-list which is set to t by default.

User Option: TeX-ispell-extend-skip-list ¶

This boolean option controls whether AUCTeX activates its extension for skipping certain macro arguments and environments when spell checking.

When non-nil, AUCTeX loads the file tex-ispell.el and adds its content to ispell-tex-skip-alists. This library can and will never be complete, but the interface can be used to add selected and private macro names within your init file or on a file local basis.

ispell-tex-skip-alists has the following structure:

(defvar ispell-tex-skip-alists
  '((;; First list
     ("\\\\addcontentsline"         ispell-tex-arg-end 2)
     ("\\\\\\([aA]lph\\|arabic\\)"  ispell-tex-arg-end)
     ("\\\\makebox"                 ispell-tex-arg-end 0)
     ("\\\\documentclass" . "\\\\begin{document}"))
    (;; Second list
     ("\\(figure\\|table\\)\\*?"  ispell-tex-arg-end 0)
     ("list"                      ispell-tex-arg-end 2)
     ("verbatim\\*?" . "\\\\end{verbatim\\*?}")))
  "Lists of regions to be skipped in TeX mode.
First list is used raw.
Second list has key placed inside \\begin{}.")

Each item is an alist and the structure of it is described in ispell-skip-region-alist:

(defvar ispell-skip-region-alist
  '((...))
  "Alist expressing beginning and end of regions not to spell check.
The alist key must be a regular expression.
Valid forms include:
  (KEY) - just skip the key.
  (KEY . REGEXP) - skip to the end of REGEXP.
                   REGEXP may be string or symbol.
  (KEY REGEXP) - skip to end of REGEXP.  REGEXP must be a string.
  (KEY FUNCTION ARGS) - FUNCTION called with ARGS
                        returns end of region.")

Let’s go through the first list of ispell-tex-skip-alists line by line:

("\\\\addcontentsline"         ispell-tex-arg-end 2)

KEY is the string "\\\\addcontentsline", FUNCTION is ispell-tex-arg-end called with ARGS, here 2. ispell-tex-arg-end is a function provided by ispell.el which skips as many subsequent optional arguments in square brackets as it sees and then skips ARGS number of mandatory arguments in braces. Omitting ARGS means skip 1 mandatory argument. In practice, when you have something like this in your document:

\addcontentsline{toc}{chapter}{Some text}

The first two arguments are left out and ‘Some text’ will be spell checked. For the next line

("\\\\\\([aA]lph\\|arabic\\)"  ispell-tex-arg-end)

the name of the counter as argument is skipped. Next line is

("\\\\makebox"                 ispell-tex-arg-end 0)

where only optional arguments are skipped, the first mandatory argument is checked, e.g.

\makebox[0pt][l]{Some text}

Finally, the next line

("\\\\documentclass" . "\\\\begin{document}"))

ensures that the entire preamble of a document is discarded. Second list works the same; it is more convenient for environments since KEY is wrapped inside \begin{}.

AUCTeX provides two functions to add items to car and cdr of ispell-tex-arg-end, namely TeX-ispell-skip-setcar and TeX-ispell-skip-setcdr. The argument of these functions is exactly as in ispell-tex-skip-alists. Additions can be done via init file, e.g.:

(eval-after-load "tex-ispell"
  '(progn
     (TeX-ispell-skip-setcar
      '(("\\\\mymacro" ispell-tex-arg-end)))
     (TeX-ispell-skip-setcdr
      '(("myverbatim" . "\\\\end{myverbatim}")))))

Another possibility is to use file local additions at the end of your TeX file, e.g.:

%%% Local Variables:
%%% mode: LaTeX
%%% TeX-master: t
%%% eval: (TeX-ispell-skip-setcar '(("\\\\mymacro" . "{[-0-9]+}")))
%%% End:

Finally, AUCTeX provides a function called TeX-ispell-tex-arg-end which sees more arguments than ispell-tex-arg-end. Refer to its doc string for more information.

AUCTeX also provides a facility to skip the argument of in-line verbatim macros like ‘\Verb’ from fancyvrb.sty or ‘\mintinline’ from minted.sty. Characters delimiting the verbatim text are stored in TeX-ispell-verb-delimiters.

User Option: TeX-ispell-verb-delimiters ¶

String with delimiters recognized for in-line verbatim macros. This variable is initialized to ‘!|#~"*/+^-’. Since this string is used to build a character alternative inside a regular expression, special characters ‘^’ and ‘-’ should come last. Other characters like opening brace ‘{’, asterisk ‘*’ or at sign ‘@’ should be avoided as they are not recognized by font-latex.el.

4.1.3 Options for TeX Processors

There are some options you can customize affecting which processors are invoked or the way this is done and which output they produce as a result. These options control if DVI or PDF output should be produced, if TeX should be started in interactive or nonstop mode, if source specials or a SyncTeX file should be produced for making inverse and forward search possible or which TeX engine should be used instead of regular TeX, like PDFTeX, Omega or XeTeX, and the style error messages are printed with.

Command: TeX-PDF-mode ¶

(C-c C-t C-p) This command toggles the PDF mode of AUCTeX, a buffer-local minor mode which is enabled by default. You can customize TeX-PDF-mode to give it a different default or set it as a file local variable on a per-document basis. This option usually results in calling either PDFTeX or ordinary TeX.

User Option: TeX-DVI-via-PDFTeX ¶

If this is set, DVI will also be produced by calling PDFTeX, setting \pdfoutput=0. This makes it possible to use PDFTeX features like character protrusion even when producing DVI files. Contemporary TeX distributions do this anyway, so that you need not enable the option within AUCTeX.

Command: TeX-interactive-mode ¶

(C-c C-t C-i) This command toggles the interactive mode of AUCTeX, a global minor mode. You can customize TeX-interactive-mode to give it a different default. In interactive mode, TeX will pause with an error prompt when errors are encountered and wait for the user to type something.

Command: TeX-source-correlate-mode ¶

(C-c C-t C-s) Toggles support for forward and inverse search. Forward search refers to jumping to the place in the previewed document corresponding to where point is located in the document source and inverse search to the other way round. See Forward and Inverse Search.

You can permanently activate TeX-source-correlate-mode by customizing the variable TeX-source-correlate-mode. There is a bunch of customization options for the mode, use M-x customize-group RET TeX-view RET to find out more.

AUCTeX is aware of three different means to do I/O correlation: source specials (only DVI output), the pdfsync LaTeX package (only PDF output) and SyncTeX. The choice between source specials and SyncTeX can be controlled with the variable TeX-source-correlate-method.

Should you use source specials it has to be stressed very strongly however, that source specials can cause differences in page breaks and spacing, can seriously interfere with various packages and should thus never be used for the final version of a document. In particular, fine-tuning the page breaks should be done with source specials switched off.

Sometimes you are requested, by journal rules or packages, to compile the document into DVI output. Thus, if you want a PDF document in the end you can either use XeTeX engine, see below for information about how to set engines, or compile the document with tex and then convert to PDF with dvips–ps2pdf before viewing it. In addition, current Japanese TeX engines cannot generate PDF directly so they rely on DVI-to-PDF converters. Usually dvipdfmx command is used for this purpose. You can use the TeX-PDF-from-DVI variable to let AUCTeX know you want to generate the final PDF by converting a DVI file.

User Option: TeX-PDF-from-DVI ¶

This option controls if and how to produce a PDF file by converting a DVI file.

When TeX-PDF-mode is non-nil, if TeX-PDF-from-DVI is non-nil too the document is compiled to DVI instead of PDF. When the document is ready, C-c C-c will suggest to run the converter to PDF or an intermediate format.

If non-nil, TeX-PDF-from-DVI should be the name of the command in TeX-command-list, as a string, used to convert the DVI file to PDF or to an intermediate format. Values currently supported are:

• "Dvips": the DVI file is converted to PS with dvips. After successfully running it, ps2pdf will be the default command to convert the PS file to PDF.
• "Dvipdfmx": the DVI file is converted to PDF with dvipdfmx.

(case is significant; note the uppercase ‘D’ in both strings) When the PDF file is finally ready, the next suggested command will be ‘View’ to open the viewer.

This option can also be set as a file local variable, in order to use this conversion on a per-document basis.

Recall the whole sequence of C-c C-c commands can be replaced by the single C-c C-a.

AUCTeX also allows you to easily select different TeX engines for processing, either by using the entries in the ‘TeXing Options’ submenu below the ‘Command’ menu or by calling the function TeX-engine-set. These eventually set the variable TeX-engine which you can also modify directly.

User Option: TeX-engine ¶

This variable allows you to choose which TeX engine should be used for typesetting the document, i.e. the executables which will be used when you invoke the ‘TeX’ or ‘LaTeX’ commands. The value should be one of the symbols defined in TeX-engine-alist-builtin or TeX-engine-alist. The symbols ‘default’, ‘xetex’, ‘luatex’ and ‘omega’ are available from the built-in list.

Note that TeX-engine is buffer-local, so setting the variable directly or via the above mentioned menu or function will not take effect in other buffers. If you want to activate an engine for all AUCTeX modes, set TeX-engine in your init file, e.g. by using M-x customize-option RET. If you want to activate it for a certain AUCTeX mode only, set the variable in the respective mode hook. If you want to activate it for certain files, set it through file variables (see File Variables in The Emacs Editor).

Should you need to change the executable names related to the different engine settings, there are some variables you can tweak. Those are TeX-command, LaTeX-command, TeX-Omega-command, LaTeX-Omega-command, ConTeXt-engine and ConTeXt-Omega-engine. The rest of the executables is defined directly in TeX-engine-alist-builtin. If you want to override an entry from that, add an entry to TeX-engine-alist that starts with the same symbol as that the entry in the built-in list and specify the executables you want to use instead. You can also add entries to TeX-engine-alist in order to add support for engines not covered per default.

User Option: TeX-engine-alist ¶

Alist of TeX engines and associated commands. Each entry is a list with a maximum of five elements. The first element is a symbol used to identify the engine. The second is a string describing the engine. The third is the command to be used for plain TeX. The fourth is the command to be used for LaTeX. The fifth is the command to be used for the --engine parameter of ConTeXt’s ‘texexec’ program. Each command can either be a variable or a string. An empty string or nil means there is no command available.

In some systems, Emacs cannot inherit the PATH environment variable from the shell and thus AUCTeX may not be able to run TeX commands. Before running them, AUCTeX checks if it is able to find those commands and will warn you in case it fails. You can skip this test by changing the option TeX-check-TeX.

User Option: TeX-check-TeX ¶

If non-nil, AUCTeX will check if it is able to find a working TeX distribution before running TeX, LaTeX, ConTeXt, etc. It actually checks if can run TeX-command command or the shell returns a command not found error. The error code returned by the shell in this case can be set in TeX-check-TeX-command-not-found option.

In addition, AUCTeX searches for a line similar to

LaTeX2e <2022-11-01> patch level 1

in the console log to check whether latex command fails or not. If there isn’t such a line when running LaTeX, AUCTeX warns the problem and resets the next default command to “LaTeX”. If this check doesn’t suit for your use case, you can customize the TeX-LaTeX-sentinel-banner-regexp option:

User Option: TeX-LaTeX-sentinel-banner-regexp ¶

When a LaTeX run doesn’t output a banner line matching this regexp, AUCTeX considers that it failed.

Some LaTeX packages requires the document to be compiled with a specific engine. Notable examples are ‘fontspec’ and ‘polyglossia’ packages, which require LuaTeX and XeTeX engines. If you try to compile a document which loads one of such packages and the set engine is not one of those allowed you will be asked to select a different engine before running the LaTeX command. If you do not want to be warned by AUCTeX in these cases, customize the option TeX-check-engine.

User Option: TeX-check-engine ¶

This boolean option controls whether AUCTeX should check the correct engine has been set before running LaTeX commands.

As shown above, AUCTeX handles in a special way most of the main options that can be given to the TeX processors. When you need to pass to the TeX processor arbitrary options not handled by AUCTeX, you can use the file local variable TeX-command-extra-options.

User Option: TeX-command-extra-options ¶

String with the extra options to be given to the TeX processor. For example, if you need to enable the shell escape feature to compile a document, add the following line to the list of local variables of the source file:

%%% TeX-command-extra-options: "-shell-escape"

By default this option is not safe as a file-local variable because a specially crafted document compiled with shell escape enabled can be used for malicious purposes.

You can customize AUCTeX to show the processor output as it is produced.

User Option: TeX-show-compilation ¶

If non-nil, the output of TeX compilation is shown in another window.

You can instruct TeX to print error messages in the form ‘file:line:error’ which is similar to the way many compilers format them.

User Option: TeX-file-line-error ¶

If non-nil, TeX will produce ‘file:line:error’ style error messages.

ConTeXt users can choose between Mark II and Mark IV versions. This is controlled by ConTeXt-Mark-version option.

User Option: ConTeXt-Mark-version ¶

This variables specifies which version of Mark should be used. Values currently supported are "II", the default, and "IV". It can be set globally using customization interface or on a per-file basis, by specifying it as a file variable.

4.2.1 Starting Viewers

Viewers are normally invoked by pressing C-c C-c once the document is formatted, which will propose the ‘View’ command, or by activating the respective entry in the Command menu. Alternatively you can type C-c C-v which calls the function TeX-view.

Command: TeX-view ¶

(C-c C-v) Start a viewer without confirmation. The viewer is started either on a region or the master file, depending on the last command issued. This is especially useful for jumping to the location corresponding to point in the viewer when using TeX-source-correlate-mode.

AUCTeX will try to guess which type of viewer (DVI, PostScript or PDF) has to be used and what options are to be passed over to it. This decision is based on the output files present in the working directory as well as the class and style options used in the document. For example, if there is a DVI file in your working directory, a DVI viewer will be invoked. In case of a PDF file it will be a PDF viewer. If you specified a special paper format like ‘a5paper’ or use the ‘landscape’ option, this will be passed to the viewer by the appropriate options. Especially some DVI viewers depend on this kind of information in order to display your document correctly. In case you are using ‘pstricks’ or ‘psfrag’ in your document, a DVI viewer cannot display the contents correctly and a PostScript viewer will be invoked instead.

The association between the tests for the conditions mentioned above and the viewers is made in the variable TeX-view-program-selection. Therefore this variable is the starting point for customization if you want to use other viewers than the ones suggested by default.

User Option: TeX-view-program-selection ¶

This is a list of predicates and viewers which is evaluated from front to back in order to find out which viewer to call under the given conditions. In the first element of each list item you can reference one or more predicates defined in TeX-view-predicate-list or TeX-view-predicate-list-builtin. In the second element you can reference a viewer defined in TeX-view-program-list or TeX-view-program-list-builtin. The viewer of the first item with a positively evaluated predicate is selected.

So TeX-view-program-selection only contains references to the actual implementations of predicates and viewer commands respectively which can be found elsewhere. AUCTeX comes with a set of preconfigured predicates and viewer commands which are stored in the variables TeX-view-predicate-list-builtin and TeX-view-program-list-builtin respectively. If you are not satisfied with those and want to overwrite one of them or add your own definitions, you can do so via the variables TeX-view-predicate-list and TeX-view-program-list.

User Option: TeX-view-predicate-list ¶

This is a list of predicates for viewer selection and invocation. The first element of each list item is a symbol and the second element a Lisp form to be evaluated. The form should return nil if the predicate is not fulfilled.

A built-in predicate from TeX-view-predicate-list-builtin can be overwritten by defining a new predicate with the same symbol.

User Option: TeX-view-program-list ¶

This is a list of viewer specifications each consisting of a symbolic name and either a command line or a function to be invoked when the viewer is called. If a command line is used, parts of it can be conditionalized by prefixing them with predicates from TeX-view-predicate-list or TeX-view-predicate-list-builtin. (See the doc string for the exact format to use.) The command line can also contain placeholders as defined in TeX-expand-list and TeX-expand-list-builtin which are expanded before the viewer is called.

The third element of each item is a string, or a list of strings, with the name of the executable, or executables, needed to open the output file in the viewer. Placeholders defined in TeX-expand-list and TeX-expand-list-builtin can be used here. This element is optional and is used to check whether the viewer is actually available on the system.

A built-in viewer spec from TeX-view-program-list-builtin can be overwritten by defining a new viewer spec with the same name.

After the viewer is called via either the ‘View’ command or the key stroke C-c C-v, the window system focus goes and stays on the viewer. If you prefer that the focus is pulled back to Emacs immediately after that and you are using evince-compatible viewer, customize the option TeX-view-enince-keep-focus.

User Option: TeX-view-evince-keep-focus ¶

When this option is non-nil and the viewer is compatible with evince, the focus is pulled back to Emacs immediately after the viewer is invoked or refreshed from within AUCTeX.

Note that the viewer selection and invocation as described above will only work if certain default settings in AUCTeX are intact. For one, the whole viewer selection machinery will only be triggered if there is no ‘%V’ expander in TeX-expand-list. So if you have trouble with the viewer invocation you might check if there is an older customization of the variable in place. In addition, the use of a function in TeX-view-program-list only works if the ‘View’ command in TeX-command-list makes use of the hook TeX-run-discard-or-function.

4.2.2 Forward and Inverse Search

Forward and inverse search refer to the correlation between the document source in the editor and the typeset document in the viewer. Forward search allows you to jump to the place in the previewed document corresponding to a certain line in the document source and inverse search vice versa.

AUCTeX supports three methods for forward and inverse search: source specials (only DVI output), the pdfsync LaTeX package (only PDF output) and SyncTeX (any type of output). If you want to make use of forward and inverse searching with source specials or SyncTeX, switch on TeX-source-correlate-mode. See Options for TeX Processors, on how to do that. The use of the pdfsync package is detected automatically if document parsing is enabled. Customize the variable TeX-source-correlate-method to select the method to use.

User Option: TeX-source-correlate-method ¶

Method to use for enabling forward and inverse search. This can be ‘source-specials’ if source specials should be used, ‘synctex’ if SyncTeX should be used, or ‘auto’ if AUCTeX should decide.

When the variable is set to ‘auto’, AUCTeX will always use SyncTeX if your latex processor supports it, source specials otherwise. You must make sure your viewer supports the same method.

It is also possible to specify a different method depending on the output, either DVI or PDF, by setting the variable to an alist of the kind

((dvi . ‘<source-specials or synctex>’)
 (pdf . ‘<source-specials or synctex>’))

in which the CDR of each entry is a symbol specifying the method to be used in the corresponding mode. The default value of the variable is

((dvi . source-specials)
 (pdf . synctex))

which is compatible with the majority of viewers.

Forward search happens automatically upon calling the viewer, e.g. by typing C-c C-v (TeX-view). This will open the viewer or bring it to front and display the output page corresponding to the position of point in the source file. AUCTeX will automatically pass the necessary command line options to the viewer for this to happen.

You can also make special mouse event do forward search at the clicked position. Use TeX-source-correlate-map² and TeX-view-mouse like this:

(eval-after-load "tex"
  '(define-key TeX-source-correlate-map [C-down-mouse-1]
               #'TeX-view-mouse))

This example binds C-down-mouse-1, which usually opens a concise menu to select buffer, to the command to do forward search.

Upon opening the viewer you will be asked if you want to start a server process (Gnuserv or Emacs server) which is necessary for inverse search. This happens only if there is no server running already. You can customize the variable TeX-source-correlate-start-server to inhibit the question and always or never start the server respectively.

User Option: TeX-source-correlate-start-server ¶

If TeX-source-correlate-mode is active and a viewer is invoked, the default behavior is to ask if a server process should be started. Set this variable to t if the question should be inhibited and the server should always be started. Set it to nil if the server should never be started. Inverse search will not be available in the latter case.

Inverse search, i.e. jumping to the part of your document source in Emacs corresponding to a certain position in the viewer, is triggered from the viewer, typically by a mouse click. Refer to the documentation of your viewer to find out how it has to be configured and what you have to do exactly. In xdvi you normally have to use C-down-mouse-1.

Note that inverse search with the Evince PDF viewer or its MATE fork Atril might fail in raising the Emacs frame after updating point in your document’s buffer. There is simply no way to raise the Emacs frame reliably accross different operating systems and different window managers with their different focus stealing policies. If the Emacs frame is not raised after performing an inverse search from Evince or Atril, you can customize the following option.

User Option: TeX-raise-frame-function ¶

A function that will be called after performing an inverse search from Evince or Atril in order to raise the current Emacs frame.

If your Emacs frame is already raised in that situation, just leave this variable set to its default value raise-frame. Otherwise, here are some alternative settings that work for some users.

;; Alternative 1: For some users, `x-focus-frame' works.
(setq TeX-raise-frame-function #'x-focus-frame)

;; Alternative 2: Under GNOME 3.20 (and probably others), it
;; seems some focus stealing prevention policy prohibits that
;; some window gets the focus immediately after the user has
;; clicked in some other window.  Here waiting a bit before
;; issuing the request seems to work.
(setq TeX-raise-frame-function
      (lambda ()
        (run-at-time 0.5 nil #'x-focus-frame)))

;; Alternative 3: Use the external wmctrl tool in order to
;; force Emacs into the focus.
(setq TeX-raise-frame-function
      (lambda ()
        (call-process
         "wmctrl" nil nil nil "-i" "-R"
         (frame-parameter (selected-frame) 'outer-window-id))))

4.3.1 Controlling warnings to be reported

Normally AUCTeX will only report real errors, but you may as well ask it to report ‘bad boxes’ and warnings as well.

Command: TeX-toggle-debug-bad-boxes ¶

(C-c C-t C-b) Toggle whether AUCTeX should stop at bad boxes (i.e. overfull and underfull boxes) as well as normal errors. The boolean option TeX-debug-bad-boxes is set accordingly.

Command: TeX-toggle-debug-warnings ¶

(C-c C-t C-w) Toggle whether AUCTeX should stop at warnings as well as normal errors. The boolean option TeX-debug-warnings is set accordingly.

While many users desire to have warnings reported after compilation, there are certain warnings that are considered unimportant and users want to ignore them. For a more fine-grained control of what kinds of warnings should be shown after compilation, AUCTeX provides other options.

User Option: TeX-ignore-warnings ¶

Controls which warnings are to be ignored.

It can be a regexp matching the message of the warnings to be ignored.

More advanced users can set also this option to a symbol with the name of a custom function taking as arguments all the information of the warning listed in TeX-error-list variable, except the last one about whether to ignore the warning. See the code of TeX-warning function and the documentation of TeX-error-list for more details.

Command: TeX-toggle-suppress-ignored-warnings ¶

(C-c C-t C-x) Toggle whether AUCTeX should actually hide the ignored warnings specified with TeX-ignore-warnings. The boolean option TeX-suppress-ignored-warnings is set accordingly. If this is nil, all warnings are shown, even those matched by TeX-ignore-warnings, otherwise these are hidden.

Note that TeX-debug-warnings takes the precedence: if it is nil, all warnings are hidden in any case.

4.3.2 List of all errors and warnings

When the option TeX-parse-all-errors is non-nil, you will be also able to open an overview of all errors and warnings reported by the TeX compiler.

Command: TeX-error-overview ¶

Show an overview of the errors and warnings occurred in the last TeX run.

In this window you can visit the error on which point is by pressing RET, and visit the next or previous issue by pressing n or p respectively. A prefix argument to these keys specifies how many errors to move forward or backward. You can visit an error also by clicking on its message. Jump to error point in the source code with j, and use l see the error in the log buffer. In addition, you can toggle visibility of bad boxes, generic warnings, and ignored warnings with b, w, and x, respectively (see Controlling warnings to be reported for details). Press q to quit the overview.

User Option: TeX-error-overview-open-after-TeX-run ¶

When this boolean variable is non-nil, the error overview will be automatically opened after running TeX if there are errors or warnings to show.

The error overview is opened in a new window of the current frame by default, but you can change this behavior by customizing the option TeX-error-overview-setup.

User Option: TeX-error-overview-setup ¶

Controls the frame setup of the error overview. The possible value is: separate-frame; with a nil value the current frame is used instead.

The parameters of the separate frame can be set with the TeX-error-overview-frame-parameters option.

If the display does not support multi frame, the current frame will be used regardless of the value of this variable.

5.4.1 Using AUCTeX with European Languages

• Typing and Displaying Non-ASCII Characters
• Style Files for Different Languages

(add-hook 'TeX-language-dk-hook
          (lambda () (ispell-change-dictionary "danish")))

5.4.2 Using AUCTeX with Japanese TeX

To write Japanese text with AUCTeX, you need the versions of TeX and Emacs that support Japanese. AUCTeX supports three Japanese TeX engines by default: NTT jTeX, ASCII pTeX and upTeX.

Activate japanese-plain-TeX-mode or japanese-LaTeX-mode to use the Japanese TeX engines. If it doesn’t work, send mail to Masayuki Ataka masayuki.ataka@gmail.com or Ikumi Keita ikumikeita@jcom.home.ne.jp, who currently concern with stuff related to Japanese in AUCTeX. None of the primary AUCTeX maintainers understand Japanese, so they cannot help you.

It is recommended to enable TeX-parse-self for typical Japanese LaTeX users. When enabled, japanese-LaTeX-mode selects the suitable Japanese TeX engine automatically based on the class file name (such as jbook, jsarticle and tjreport) and its option. See Automatic Parsing of TeX Files.

It is important to select the suitable Japanese TeX engine because the selected engine determines the command name such as platex and uptex to typeset the document. If you find that wrong command is used, check the value of TeX-engine on that buffer. If the value does not suit the current document, change the value by the ‘TeXing Options’ submenu below the ‘Command’ menu. See Options for TeX Processors.

To make the selected engine to persist across Emacs sessions, there are two ways from which you can choose one according to your needs:

1. If you use a specific engine (almost) exclusively, customize the option japanese-TeX-engine-default.

   User Option: japanese-TeX-engine-default ¶

   The default TeX-engine in Japanese TeX mode.

   The default value is ‘ptex’.

2. If you want to set the engine on a per file basis, use the file local variables to set TeX-engine.

   Here is a sample code to set TeX-engine to ‘uptex’:

   %%% Local Variables:
   %%% mode: japanese-LaTeX
   %%% TeX-engine: uptex
   %%% End:
   

In the both cases above, the valid value is one of ‘ptex’, ‘jtex’ and ‘uptex’.

You can override the command names associated with the above three engines or define your own engine by customizing TeX-engine-alist. See Options for TeX Processors.

It is sometimes necessary to use an engine which differs from the one AUCTeX selects automatically. For example, even when you want to use j-article document class deliberately with ASCII pLaTeX, AUCTeX selects NTT jLaTeX command if TeX-parse-self is enabled, because j-article originally belongs to NTT jLaTeX. In such cases, use the file local variable method above to select the engine you intend to use.

If you usually use AUCTeX in Japanese, setting the following variables is useful.

User Option: TeX-default-mode ¶

Mode to enter for a new file when it cannot be determined whether the file is plain TeX or LaTeX or what.

If you want to enter Japanese LaTeX mode whenever this may happen, set the variable like this:

(setq TeX-default-mode 'japanese-LaTeX-mode)

User Option: japanese-LaTeX-default-style ¶

The default style/class when creating a new Japanese LaTeX document.

The default value is ‘"jarticle"’.

It is recommended also for Japanese users to customize the option TeX-PDF-from-DVI to ‘"Dvipdfmx"’. See Options for TeX Processors.

There are three customize options with regard to the encoding of Japanese text.

User Option: japanese-TeX-use-kanji-opt-flag ¶

If non-nil, AUCTeX adds -kanji option to the typesetting command when TeX-engine is ‘ptex’.

Usually AUCTeX guesses the right coding systems for input to and output from the Japanese TeX process, but you can override them by the following two customize options.

User Option: TeX-japanese-process-input-coding-system ¶

If non-nil, used for encoding input to Japanese TeX process. When nil, AUCTeX tries to choose suitable coding system.

User Option: TeX-japanese-process-output-coding-system ¶

If non-nil, used for decoding output from Japanese TeX process. When nil, AUCTeX tries to choose suitable coding system.

The former customize options japanese-TeX-command-default, japanese-LaTeX-command-default and japanese-TeX-command-list are removed from AUCTeX. Use japanese-TeX-engine-default instead. If you need to customize the executable file name such as ‘"latex"’, the options for them, or both, customize TeX-engine-alist.

The following two additional font commands are available in LaTeX mode buffer.

C-c C-f g ¶

Insert gothic font command ‘\textgt{∗}’ or ‘\mathgt{∗}’ depending on the context.

C-c C-f m ¶

Insert mincho font command ‘\textmc{∗}’ or ‘\mathmc{∗}’ depending on the context.

Although they are meaningful only with ‘ptex’ and ‘uptex’ engines, it won’t matter in buffers with other engines.

See tex-jp.el for more information.

5.5.1 Automatic Customization for the Site

Assuming that the automatic customization at the global level was done when AUCTeX was installed, your choice is now: will you use it? If you use it, you will benefit by having access to all the symbols and environments available for completion purposes. The drawback is slower load time when you edit a new file and perhaps too many confusing symbols when you try to do a completion.

You can disable the automatic generated global style hooks by setting the variable 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.

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.

5.5.2 Automatic Customization for a User

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

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

User Option: TeX-macro-private ¶

Directories where you store your personal TeX macros. The value defaults to the directories listed in the TEXINPUTS and BIBINPUTS environment variables or to the respective directories in $TEXMFHOME of kpsewhich setting if no results can be obtained from the environment variables.

User Option: TeX-auto-private ¶

List of directories containing automatically generated AUCTeX style files. These correspond to the personal TeX macros.

Command: TeX-auto-generate tex auto ¶

(M-x TeX-auto-generate RET) 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 ¶

List of directories containing hand generated AUCTeX style files. These correspond to the personal TeX macros.

5.5.3 Automatic Customization for a Directory

AUCTeX can update the style information about a file each time you save it if TeX-auto-save option is enabled. Saved information will be stored in the directory TeX-auto-local, set to ‘"auto"’ by default.

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.

These correspond to TeX macros found in the current directory.

User Option: TeX-auto-local ¶

Directory containing automatically generated TeX information.

These correspond to TeX macros found in the current directory.

User Option: TeX-auto-save-aggregate ¶

When non-nil, save parsed information in auto subdirectory of master directory.

Otherwise, save in each auto subdirectory of the parsed file.

Subdirectory name is actually taken from TeX-auto-local.

5.6.1 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"
 (lambda () 
   (LaTeX-largest-level-set "part"))
 TeX-dialect)

The example is from the AUCTeX sources and is loaded for any LaTeX document using the book document class (or style before LaTeX2e). (Note that the above code is much simplified for explanatory purpose.) The file specifies that the largest kind of section in such a document is ‘part’. The interesting thing to notice is that the style file defines an (anonymous) function, and adds it to the list of loaded style hooks by calling TeX-add-style-hook.

The first time the user indirectly tries to access some style-specific information, such as the largest sectioning command available, the style hooks for all files directly or indirectly read by the current document are executed. The actual files will only be evaluated once, but the hooks will be called for each buffer using the style file.

Note that the basename of the style file and the name of the style hook should usually be identical.

Function: TeX-add-style-hook style hook &optional dialect-expr ¶

Add hook to the list of functions to run when we use the TeX file style and the current dialect is one in the set derived from dialect-expr. When dialect-expr is omitted, then hook is allowed to be run whatever the current dialect is.

dialect-expr may be one of:

• A symbol indicating a singleton containing one basic TeX dialect, this symbol shall be selected among:

  :latex

  For all files in LaTeX mode, or any mode derived thereof.

  :bibtex

  For all files in BibTeX mode, or any mode derived thereof.

  :texinfo

  For all files in Texinfo mode.

  :plain-tex

  For all files in plain-TeX mode, or any mode derived thereof.

  :context

  For all files in ConTeXt mode.

  :classopt

  For class options of LaTeX document. This is provided as pseudo-dialect for style hooks associated with class options.

• A logical expression like:

  (or dialect-expression1 … dialect-expression_n)

  For union of the sets of dialects corresponding to dialect-expression1 through dialect-expression_n

  (and dialect-expression1 … dialect-expression_n)

  For intersection of the sets of dialects corresponding to dialect-expression1 through dialect-expression_n

  (nor dialect-expression1 … dialect-expression_n)

  For complement of the union sets of dialects corresponding to dialect-expression1 through dialect-expression_n relatively to the set of all supported dialects

  (not dialect-expr)

  For complement set of dialect corresponding to dialect-expr relatively to the set of all supported dialects

In case of adding a style hook for LaTeX, when calling function TeX-add-style-hook it is thought more futureproof for argument dialect-expr to pass constant TeX-dialect currently defined to :latex, rather than passing :latex directly.

Constant: TeX-dialect ¶

Default dialect for use with function TeX-add-style-hook for argument dialect-expr when the hook is to be run only on LaTeX file, or any mode derived thereof.

5.6.2 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"
 (lambda ()
   (TeX-add-symbols
    '("arabic" TeX-arg-counter)
    '("label" TeX-arg-define-label)
    '("ref" TeX-arg-ref)
    '("newcommand" TeX-arg-define-macro [ "Number of arguments" ] t)
    '("newtheorem" TeX-arg-define-environment
      [ TeX-arg-environment "Numbered like" ]
      t [ TeX-arg-counter "Within counter" ]))))

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 of the symbol, the remaining elements describe each argument.

If there are no additional elements, the symbol will be inserted with point inside braces. Otherwise, each argument of this function should match an argument of the TeX macro. What is done depends on the argument type.

If a macro is defined multiple times, AUCTeX will choose the one with the longest definition (i.e. the one with the most arguments).

Thus, to overwrite

        '("tref" 1) ; one argument

you can specify

        '("tref" TeX-arg-ref 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.

You can use the following types of specifiers for arguments:

string

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

number

Insert that many braces, leave point inside the first. 0 and -1 are special. 0 means that no braces are inserted. -1 means that braces are inserted around the macro and an active region (e.g. ‘{\tiny foo}’). If there is no active region, no braces are inserted.

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-arg-conditional ¶

Implements if expr then else. If expr evaluates to true, parse then as an argument list, else parse else as an argument list.

TeX-arg-literal ¶

Insert its arguments into the buffer. Used for specifying extra syntax for a macro.

TeX-arg-free ¶

Parse its arguments but use no braces when they are inserted.

TeX-arg-eval ¶

Evaluate arguments and insert the result in the buffer.

TeX-arg-label ¶

Prompt for a label completing with known labels. If RefTeX is active, prompt for the reference format.

TeX-arg-ref ¶

Prompt for a label completing with known labels. If RefTeX is active, do not prompt for the reference format. Usually, reference macros should use this function instead of TeX-arg-label.

TeX-arg-index-tag ¶

Prompt for an index tag. This is the name of an index, not the entry.

TeX-arg-index ¶

Prompt for an index entry completing with known entries.

TeX-arg-length ¶

Prompt for a LaTeX length completing with known lengths.

TeX-arg-macro ¶

Prompt for a TeX macro with completion.

TeX-arg-date ¶

Prompt for a date, defaulting to the current date. The format of the date is specified by the TeX-date-format option. If you want to change the format when the ‘babel’ package is loaded with a specific language, set TeX-date-format inside the appropriate language hook (for details see Using AUCTeX with European Languages).

TeX-arg-version ¶

Prompt for the version of a file, using as initial input the current date.

TeX-arg-environment ¶

Prompt for a LaTeX environment with completion.

TeX-arg-cite ¶

Prompt for a BibTeX citation. If the variable TeX-arg-cite-note-p is non-nil, ask also for optional note in citations.

TeX-arg-counter ¶

Prompt for a LaTeX counter completing with known counters.

TeX-arg-savebox ¶

Prompt for a LaTeX savebox completing with known saveboxes.

TeX-arg-file ¶

Prompt for a filename in the current directory, and use it with the extension.

TeX-arg-file-name ¶

Prompt for a filename and use as initial input the name of the file being visited in the current buffer, with extension.

TeX-arg-file-name-sans-extension ¶

Prompt for a filename and use as initial input the name of the file being visited in the current buffer, without extension.

TeX-arg-input-file ¶

Prompt for the name of an input file in TeX’s search path, and use it without the extension. Run the style hooks for the file. (Note that the behavior (type of prompt and inserted file name) of the function can be controlled by the variable TeX-arg-input-file-search.)

TeX-arg-define-label ¶

Prompt for a label completing with known labels. Add label to list of defined labels.

TeX-arg-define-length ¶

Prompt for a LaTeX length completing with known lengths. Add length to list of defined lengths.

TeX-arg-define-macro ¶

Prompt for a TeX macro with completion. Add macro to list of defined macros.

TeX-arg-define-environment ¶

Prompt for a LaTeX environment with completion. Add environment to list of defined environments.

TeX-arg-define-cite ¶

Prompt for a BibTeX citation.

TeX-arg-define-counter ¶

Prompt for a LaTeX counter.

TeX-arg-define-savebox ¶

Prompt for a LaTeX savebox.

TeX-arg-document ¶

Prompt for a LaTeX document class, using LaTeX-default-style as default value and LaTeX-default-options as default list of options. If the variable TeX-arg-input-file-search is t, you will be able to complete with all LaTeX classes available on your system, otherwise classes listed in the variable LaTeX-style-list will be used for completion. It is also provided completion for options of many common classes.

LaTeX-arg-usepackage ¶

Prompt for LaTeX packages. If the variable TeX-arg-input-file-search is t, you will be able to complete with all LaTeX packages available on your system. It is also provided completion for options of many common packages.

TeX-arg-bibstyle ¶

Prompt for a BibTeX style file completing with all style available on your system.

TeX-arg-bibliography ¶

Prompt for BibTeX database files completing with all databases available on your system.

TeX-arg-corner ¶

Prompt for a LaTeX side or corner position with completion.

TeX-arg-lr ¶

Prompt for a LaTeX side with completion.

TeX-arg-tb ¶

Prompt for a LaTeX side with completion.

TeX-arg-pagestyle ¶

Prompt for a LaTeX pagestyle with completion.

TeX-arg-verb ¶

Prompt for delimiter and text.

TeX-arg-verb-delim-or-brace ¶

Prompt for delimiter and text. This function is similar to TeX-arg-verb, but is intended for macros which take their argument enclosed in delimiters or in braces.

TeX-arg-pair ¶

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

TeX-arg-size ¶

Insert width and height as a pair. No arguments.

TeX-arg-coordinate ¶

Insert x and y coordinates as a pair. No arguments.

LaTeX-arg-author ¶

Prompt for document author, using LaTeX-default-author as initial input.

TeX-read-hook ¶

Prompt for a LaTeX hook and return it.

TeX-arg-hook ¶

Prompt for a LaTeX hook and insert it as a TeX macro argument.

TeX-read-key-val ¶

Prompt for a ‘key=value’ list of options and return them.

TeX-arg-key-val ¶

Prompt for a ‘key=value’ list of options and insert it as a TeX macro argument.

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

Some packages provide macros that are rarely useful to non-expert users. Those should be marked as expert macros using TeX-declare-expert-macros.

Function: TeX-declare-expert-macros style macros... ¶

Declare macros as expert macros of style.

Expert macros are completed depending on TeX-complete-expert-commands.

5.6.3 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"
 (lambda ()
   (LaTeX-add-environments
    '("document" LaTeX-env-document)
    '("enumerate" LaTeX-env-item)
    '("itemize" LaTeX-env-item)
    '("list" LaTeX-env-list))))

It is completely up to the environment hook to insert the environment, but the function LaTeX-insert-environment may be of some help. The hook will be called with the name of the environment as its first argument, and extra arguments can be provided by adding them to a list after the hook.

For simple environments with arguments, for example defined with ‘\newenvironment’, you can make AUCTeX prompt for the arguments by giving the prompt strings in the call to LaTeX-add-environments. The fact that an argument is optional can be indicated by wrapping the prompt string in a vector.

For example, if you have defined a loop environment with the three arguments from, to, and step, you can add support for them in a style file.

%% loop.sty

\newenvironment{loop}[3]{...}{...}

;; loop.el

(TeX-add-style-hook
 "loop"
 (lambda ()
   (LaTeX-add-environments
    '("loop" "From" "To" "Step"))))

If an environment is defined multiple times, AUCTeX will choose the one with the longest definition. Thus, if you have an enumerate style file, and want it to replace the standard LaTeX enumerate hook above, you could define an enumerate.el file as follows, and place it in the appropriate style directory.

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

(defun LaTeX-env-enumerate (environment &optional _ignore) ...)

The symbol foo will be passed to LaTeX-env-enumerate 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.

Following is a list of available hooks for LaTeX-add-environments:

LaTeX-env-item ¶

Insert the given environment and the first item.

LaTeX-env-item-args ¶

Insert the given environment plus further arguments, and the first item. You can use this as a hook in case you want to specify multiple complex arguments just like in elements of TeX-add-symbols. Here is an example from enumitem.el in order to prompt for a ‘key=value’ list to be inserted as an optional argument to the ‘itemize’ environment:

(LaTeX-add-environments
 '("itemize" LaTeX-env-item-args
   [TeX-arg-key-val (LaTeX-enumitem-key-val-options)]))

LaTeX-env-figure ¶

Insert the given figure-like environment with a caption and a label.

LaTeX-env-array ¶

Insert the given array-like environment with position and column specifications.

LaTeX-env-label ¶

Insert the given environment with a label.

LaTeX-env-label-args ¶

Insert the given environment with a label and further arguments to the environment.

LaTeX-env-list ¶

Insert the given list-like environment, a specifier for the label and the first item.

LaTeX-env-minipage ¶

Insert the given minipage-like environment with position and width specifications.

LaTeX-env-tabular* ¶

Insert the given tabular*-like environment with width, position and column specifications.

LaTeX-env-picture ¶

Insert the given environment with width and height specifications.

LaTeX-env-bib ¶

Insert the given environment with a label for a bibitem.

LaTeX-env-contents ¶

Insert the given environment with a filename as its argument.

LaTeX-env-args ¶

Insert the given environment with arguments. You can use this as a hook in case you want to specify multiple complex arguments just like in elements of TeX-add-symbols. This is most useful if the specification of arguments to be prompted for with strings and strings wrapped in a vector as described above is too limited.

Here is an example from listings.el which calls a function with one argument in order to prompt for a ‘key=value’ list to be inserted as an optional argument of the ‘lstlisting’ environment:

(LaTeX-add-environments
 '("lstlisting" LaTeX-env-args
   [TeX-arg-key-val (LaTeX-listings-key-val-options)]))

Some packages provide environments that are rarely useful to non-expert users. Those should be marked as expert environments using LaTeX-declare-expert-environments.

Function: LaTeX-declare-expert-environments style environments... ¶

Declare environments as expert environments of style.

Expert environments are completed depending on TeX-complete-expert-commands.

5.6.4 Adding or Examining Other Information

• Adding bibliographies in style hooks
• Examining Package/Class Options
• Adding Support for Option Completion