auctex: Selecting a Command
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 ((emacs)File Variables).
-- 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'.