2.6 Completion

Emacs lisp programmers probably know the lisp-complete-symbol command which was bound to M-<TAB> until completion-at-point became the new standard completion facility (see below). Users of the wonderful ispell mode know and love the ispell-complete-word command from that package. Similarly, AUCTeX has a TeX-complete-symbol command, by default bound to M-<TAB> which is equivalent to C-M-i. Using TeX-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 M-<TAB> will now complete as much of the macro, as it unambiguously can. For example, if you type ‘‘\renewc’’ and then M-<TAB>, it will expand to ‘‘\renewcommand’’. But there’s more: if point is just after ‘\begin{’, then TeX-complete-symbol will complete LaTeX environments, etc. This is controlled by TeX-complete-list.

Command: TeX-complete-symbol

(M-<TAB>) Complete TeX symbol before point.

Variable: TeX-complete-list

List of ways to complete the preceding text.

Each entry is a list with the following elements:

1. Regexp matching the preceding text or a predicate of arity 0 which returns non-nil and sets ‘match-data’ appropriately if it is applicable.
2. A number indicating the subgroup in the regexp containing the text.
3. A function returning an alist of possible completions.
4. Text to append after a succesful completion.

Or alternatively:

1. Regexp matching the preceding text.
2. Function to do the actual completion.

More recent Emacs versions have a new completion mechanism. Modes may define and register custom completion-at-point functions and when the user invokes completion-at-point (usually bound to M-<TAB>), all such registered functions are consulted for checking for possible completions. Modern completion UIs like company-mode or corfu support this completion-at-point facility.

Function: TeX--completion-at-point

AUCTeX’s completion-at-point function which is automatically added to completion-at-point-functions in TeX and LaTeX buffers.

It offers the same completion candidates as would TeX-complete-symbol (and is also controlled by TeX-complete-list) except that it doesn’t fall back on ispell-complete-word which would be awkward with completion UIs like company-mode.

Function: LaTeX--arguments-completion-at-point

AUCTeX’s completion-at-point function inside arguments which is automatically added to completion-at-point-functions in LaTeX buffers.

It offers the completion candidates stored in the variables TeX-symbol-list and LaTeX-environment-list for single candidate, multiple candidates separated by commas, or key-value candidates separated by commas and/or equal signs.

A more direct way to insert a macro is with TeX-insert-macro, bound to C-c C-m which is equivalent to C-c <RET>. It has the advantage over completion that it knows about the argument of most standard LaTeX macros, and will prompt for them. It also knows about the type of the arguments, so it will for example give completion for the argument to ‘\include’. Some examples are listed below.

Command: TeX-insert-macro

(C-c C-m or C-c <RET>) Prompt (with completion) for the name of a TeX macro, and if AUCTeX knows the macro, prompt for each argument.

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

User Option: TeX-default-macro

Default macro to insert when invoking TeX-insert-macro first time.

User Option: TeX-insert-macro-default-style

Specifies whether TeX-insert-macro will ask for all optional arguments.

If set to the symbol show-optional-args, TeX-insert-macro asks for optional arguments of TeX marcos, unless the previous optional argument has been rejected. If set to show-all-optional-args, TeX-insert-macro asks for all optional arguments. mandatory-args-only, TeX-insert-macro asks only for mandatory arguments. When TeX-insert-macro is called with prefix argument (C-u), it’s the other way round.

Note that for some macros, there are special mechanisms, e.g. TeX-arg-cite-note-p and LaTeX-includegraphics-options-alist.

A faster alternative is to enable the option TeX-electric-escape.

User Option: TeX-electric-escape

If this is non-nil, typing the TeX escape character \ will invoke the command TeX-electric-macro.

In Texinfo mode, the command is invoked by @ instead.

The difference between TeX-insert-macro and TeX-electric-macro is that space key <SPC> will complete and exit from the minibuffer in TeX-electric-macro. Use <TAB> if you merely want to complete.

Command: TeX-electric-macro

Prompt (with completion) for the name of a TeX macro, and if AUCTeX knows the macro, prompt for each argument. Space (<SPC>) will complete and exit.

By default AUCTeX will put an empty set braces ‘{}’ after a macro with no arguments to stop it from eating the next whitespace. This is suppressed inside math mode and can be disabled totally by setting TeX-insert-braces to nil.

User Option: TeX-insert-braces

If non-nil, append a empty pair of braces after inserting a macro with no arguments.

User Option: TeX-insert-braces-alist

Control the insertion of a pair of braces after a macro on a per macro basis.

This variable is an alist. Each element is a cons cell, whose car is the macro name, and the cdr is non-nil or nil, depending on whether a pair of braces should be, respectively, appended or not to the macro.

If a macro has an element in this variable, AUCTeX will use its value to decide what to do, whatever the value of the variable TeX-insert-braces.

Completions work because AUCTeX can analyze TeX files, and store symbols in Emacs Lisp files for later retrieval. See Automatic, for more information.

AUCTeX distinguishes normal and expert macros. By default, it will offer completion only for normal commands. This behavior can be controlled using the user option TeX-complete-expert-commands.

User Option: TeX-complete-expert-commands

Complete macros and environments marked as expert commands.

Possible values are nil, t, or a list of style names.

nil

Don’t complete expert commands (default).

t

Always complete expert commands.

(styles …)

Only complete expert commands of styles.

AUCTeX will also make completion for many macro arguments, for example existing labels when you enter a ‘\ref’ macro with TeX-insert-macro or TeX-electric-macro, and BibTeX entries when you enter a ‘\cite’ macro. For this kind of completion to work, parsing must be enabled as described in Parsing Files. For ‘\cite’ you must also make sure that the BibTeX files have been saved at least once after you enabled automatic parsing on save, and that the basename of the BibTeX file does not conflict with the basename of one of TeX files.

This document was generated on January 17, 2024 using texi2html 1.82.