Next: Customization, Previous: Display, Up: top [Contents][Index]
The most powerful features of AUCTeX may be those allowing you to run
TeX, LaTeX, ConTeXt and other external commands like BibTeX
and makeindex from within Emacs, viewing and printing the
results, and moreover allowing you to debug your documents.
AUCTeX comes with a special tool bar for TeX and LaTeX which
provides buttons for the most important commands. You can enable or
disable it by customizing the options plain-TeX-enable-toolbar
and LaTeX-enable-toolbar in the TeX-tool-bar customization
group.
| • Commands | Invoking external commands. | |
| • Viewing | Invoking external viewers. | |
| • Debugging | Debugging TeX and LaTeX output. | |
| • Checking | Checking the document. | |
| • Control | Controlling the processes. | |
| • Cleaning | Cleaning intermediate and output files. | |
| • Documentation | Documentation about macros and packages. |
Next: Viewing, Up: Processing [Contents][Index]
Formatting the document with TeX, LaTeX or ConTeXt, viewing
with a previewer, printing the document, running BibTeX, making an
index, or checking the document with lacheck or
chktex all require running an external command.
| • Starting a Command | Starting a Command on a Document or Region | |
| • Selecting a Command | Selecting and Executing a Command | |
| • Processor Options | Options for TeX Processors |
Next: Selecting a Command, Up: Commands [Contents][Index]
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.
(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.
(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.
(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.
(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.
(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.
The name of the file for temporarily storing the text when formatting the current region.
A regular expression matching the end of the header. By default, this is ‘\begin{document}’ in LaTeX mode and ‘%**end of header’ in TeX mode.
A regular expression matching the start of the trailer. By default, this is ‘\end{document}’ in LaTeX mode and ‘\bye’ in 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).
(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.
AUCTeX will allow one process for each document, plus one process for the region file to be active at the same time. Thus, if you are editing n different documents, you can have n plus one processes running at the same time. If the last process you started was on the region, the commands described in Debugging and Control will work on that process, otherwise they will work on the process associated with the current document.
Next: Processor Options, Previous: Starting a Command, Up: Commands [Contents][Index]
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).
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.
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.
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.
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.
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.
Previous: Selecting a Command, Up: Commands [Contents][Index]
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.
(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.
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.
(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.
(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 I/O Correlation.
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.
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,
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 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 replace 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.
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-variable <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.
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 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.
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.
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.
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.
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.
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.
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.
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.
Next: Debugging, Previous: Commands, Up: Processing [Contents][Index]
AUCTeX allows you to start external programs for previewing the formatted output of your document.
| • Starting Viewers | Starting viewers | |
| • I/O Correlation | Forward and inverse search |
Next: I/O Correlation, Up: Viewing [Contents][Index]
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.
(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.
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.
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.
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.
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.
Note also that the implementation described above replaces an older one
which was less flexible. This old implementation works with the
variables TeX-output-view-style and TeX-view-style which
are used to associate file types and style options with viewers. If
desired you can reactivate it by using the placeholder ‘%vv’ for
the View command in TeX-command-list. Note however, that it is
bound to be removed from AUCTeX once the new implementation proved to
be satisfactory. For the time being, find a short description of the
mentioned customization options below.
List of output file extensions, style options and view options. Each
item of the list consists of three elements. If the first element (a
regular expression) matches the output file extension, and the second
element (a regular expression) matches the name of one of the style
options, any occurrence of the string %V in a command in
TeX-command-list will be replaced with the third element.
List of style options and view options. This is the predecessor of
TeX-output-view-style which does not provide the possibility to
specify output file extensions. It is used as a fallback in case none
of the alternatives specified in TeX-output-view-style match. In
case none of the entries in TeX-view-style match either, no
suggestion for a viewer is made.
Previous: Starting Viewers, Up: Viewing [Contents][Index]
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 Processor Options, 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.
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.
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.
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.
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))))
Next: Checking, Previous: Viewing, Up: Processing [Contents][Index]
Once you’ve formatted your document you may ‘debug’ it, i.e. browse through the errors (La)TeX reported. You may also have a look at a nicely formatted list of all errors and warnings reported by the compiler.
(C-c `) Go to the next error reported by TeX. The view will be split in two, with the cursor placed as close as possible to the error in the top view. In the bottom view, the error message will be displayed along with some explanatory text.
An optional numeric arg, positive or negative, specifies how many
error messages to move. A negative arg means to move back to
previous error messages, see also TeX-previous-error.
The optional reparse argument makes AUCTeX reparse the error message buffer and start the debugging from the first error. This can also be achieved by calling the function with a prefix argument (C-u).
(M-g p) Go to the previous error reported by TeX. An optional
numeric arg specifies how many error messages to move backward.
This is like calling TeX-next-error with a negative argument.
The command TeX-previous-error works only if AUCTeX can parse
the whole TeX log buffer. This is controlled by the
TeX-parse-all-errors variable.
If t, AUCTeX automatically parses the whole output log buffer right
after running a TeX command, in order to collect all warnings and
errors. This makes it possible to navigate back and forth between the
error messages using TeX-next-error and
TeX-previous-error. This is the default. If nil, AUCTeX does
not parse the whole output log buffer and TeX-previous-error
cannot be used.
As default, AUCTeX will display a special help buffer containing the error reported by TeX along with the documentation. There is however an ‘expert’ option, which allows you to display the real TeX output.
If t AUCTeX will automatically display a help text whenever an error
is encountered using TeX-next-error (C-c `). If nil a
terse information about the error is displayed in the echo area. If
expert AUCTeX will display the output buffer with the raw
TeX output.
| • Ignoring warnings | Controlling warnings to be reported | |
| • Error overview | List of all errors and warnings |
Next: Error overview, Up: Debugging [Contents][Index]
Normally AUCTeX will only report real errors, but you may as well ask it to report ‘bad boxes’ and warnings as well.
(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.
(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.
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.
(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.
Previous: Ignoring warnings, Up: Debugging [Contents][Index]
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.
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 on 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 Ignoring warnings for details). Press q to quit the overview.
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.
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.
Next: Control, Previous: Debugging, Up: Processing [Contents][Index]
Running TeX or LaTeX will only find regular errors in the
document, not examples of bad style. Furthermore, description of the
errors may often be confusing. The utilities lacheck and
chktex can be used to find style errors, such as forgetting to
escape the space after an abbreviation or using ‘...’ instead of
‘\ldots’ and other similar problems. You start lacheck with
C-c C-c Check RET and chktex with C-c C-c ChkTeX
RET. The result will be a list of errors in the
‘*compilation*’ buffer. You can go through the errors with
C-x ` (next-error, see Compilation in The Emacs
Editor), which will move point to the location of the next error.
Alternatively, you may want in-buffer notation. AUCTeX provides support for this using the Flymake package in Emacs 26 or newer (See Using Flymake in GNU Flymake for details). To enable, call M-x flymake-mode RET in the buffer or enable it in all buffers by adding this to your init file:
(add-hook 'LaTeX-mode-hook #'flymake-mode)
Note that AUCTeX currently only provides support for using
chktex as the flymake backend.
Each of the two utilities lacheck and chktex will find
some errors the other doesn’t, but chktex is more configurable,
allowing you to create your own errors. You may need to install the
programs before using them. You can get lacheck from
<URL:https://www.ctan.org/pkg/lacheck> and
chktex from
<URL:https://www.ctan.org/pkg/chktex>.
Next: Cleaning, Previous: Checking, Up: Processing [Contents][Index]
A number of commands are available for controlling the output of an application running under AUCTeX
(C-c C-k) Kill currently running external application. This may be either of TeX, LaTeX, previewer, BibTeX, etc.
(C-c C-l) Recenter the output buffer so that the bottom line is visible.
(C-c ^) Go to the ‘master’ file in the document associated with the current buffer, or if already there, to the file where the current process was started.
Next: Documentation, Previous: Control, Up: Processing [Contents][Index]
Remove generated intermediate files. In case a prefix argument is given, remove output files as well.
Canonical access to the function is provided by the ‘Clean’ and
‘Clean All’ entries in TeX-command-list, invokable with
C-c C-c or the Command menu.
The patterns governing which files to remove can be adapted separately
for each AUCTeX mode by means of the variables
plain-TeX-clean-intermediate-suffixes,
plain-TeX-clean-output-suffixes,
LaTeX-clean-intermediate-suffixes,
LaTeX-clean-output-suffixes,
docTeX-clean-intermediate-suffixes,
docTeX-clean-output-suffixes,
Texinfo-clean-intermediate-suffixes,
Texinfo-clean-output-suffixes,
ConTeXt-clean-intermediate-suffixes,
ConTeXt-clean-output-suffixes,
AmSTeX-clean-intermediate-suffixes and
AmSTeX-clean-output-suffixes.
Control if deletion of intermediate and output files has to be confirmed before it is actually done. If non-nil, ask before deleting files.
Previous: Cleaning, Up: Processing [Contents][Index]
(C-c ?) Get documentation about the packages installed on your system, using ‘texdoc’ to find the manuals. The function will prompt for the name of packages. If point is on a word, this will be suggested as default.
If the command is called with a prefix argument, you will be shown a list of manuals of the given package among to choose.
The command can be invoked by the key binding mentioned above as well as the ‘Find Documentation...’ entry in the mode menu.
Previous: Cleaning, Up: Processing [Contents][Index]