auctex: Completion
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 'M-C-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 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.
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-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.
'LaTeX-includegraphics-options-alist' and 'TeX-arg-cite-note-p'.
-- User Option: TeX-default-macro
Default macro to insert when invoking 'TeX-insert-macro' first
time.
A faster alternative is to bind the function 'TeX-electric-macro' to
'\'. This can be done by setting the variable 'TeX-electric-escape'
-- User Option: TeX-electric-escape
If this is non-nil when AUCTeX is loaded, the TeX escape character
'\' will be bound to 'TeX-electric-macro'
The difference between 'TeX-insert-macro' and 'TeX-electric-macro' is
that space 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 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 can
be stopped by entering 'LaTeX-math-mode', 
Mathematics, or 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.
-- 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, 'TeX-parse-macro' will
use its value to decided 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. 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.
Info Catalog
auctex: Mathematics
auctex: Editing
auctex: Marking