[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The most powerful features of AUCTeX may be those allowing you to
run (La)TeX/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.
7.1 Executing Commands | Invoking external commands. | |
7.2 Viewing the formatted output | Invoking external viewers. | |
7.3 Catching the errors | Debugging TeX and LaTeX output. | |
7.4 Checking for problems | Checking the document. | |
7.5 Controlling the output | Controlling the processes. | |
7.6 Cleaning intermediate and output files | ||
7.7 Documentation about macros and packages |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [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.
There are two ways to run an external command, you can either run it on
all of the current documents 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
.
See section Installing AUCTeX, for a discussion about TeX-command-list
and
Multifile Documents for a discussion about TeX-master
.
(C-c C-r) Query the user for a command, and run it on the “region
file”. Some commands (typically those invoking TeX or LaTeX)
will write the current region into the region file, after extracting the
header and tailer from the master file. If mark is inactive (which can
happen with transient-mark-mode
), use the old 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-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
.
(C-c C-b) Query the user for a command, and run it on the “region file”. Some commands (typically those invoking TeX or LaTeX) will write the current buffer into the region file, after extracting the header and tailer from the master file. See above for details.
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 Catching the errors and Controlling the output will work on that process, otherwise they will work on the process associated with the current document.
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.
AUCTeX will try to guess what command you want to invoke, but by
default it will assume that you want to run TeX in TeX mode and
LaTeX in LaTeX mode. You can overwrite this by setting the
variable TeX-command-default
.
The default command to run in this buffer. Must be an entry in
TeX-command-list
.
If you want to overwrite the values of TeX-header-end
,
TeX-trailer-start
, or TeX-command-default
, you can do that
for all files by setting them in either TeX-mode-hook
,
plain-TeX-mode-hook
, or LaTeX-mode-hook
. To overwrite
them for a single file, define them as file variables (see (emacs)File Variables section `File Variables' in The Emacs Editor). You do this by putting special
formatted text near the end of the file.
%%% Local Variables: %%% TeX-header-end: "% End-Of-Header" %%% TeX-trailer-start: "% Start-Of-Trailer" %%% TeX-command-default: "SliTeX" %%% End: |
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.
(C-c C-t C-p)
This command toggles the PDF mode of AUCTeX, a buffer-local
minor mode. You can customize TeX-PDF-mode
to give it a
different default. The default is used when AUCTeX does not have
additional clue about what a document might want. 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
packages like ‘pdfcprot’ even when producing DVI
files. Some modern TeX distributions, e.g. teTeX 3.0, do this
anyway, so that you need not enable it 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 Source Special support. Source Specials will move the DVI viewer to the location corresponding to point (forward search), and it will use ‘emacsclient’ or ‘gnuclient’ to have the previewer move Emacs to a location corresponding to a control-click in the previewer window. See section Viewing the formatted output.
You can permanently activate TeX-source-specials-mode
with
(TeX-source-specials-mode 1) |
or by customizing the variable TeX-source-specials-mode
.
There is a bunch of customization options, use customize-group
on
the group ‘TeX-source-specials’ to find out more.
It has to be stressed very strongly however, that Source Specials can cause differences in page breaks, in 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.
(C-c C-t C-o)
This command toggles the use of the Omega mode of AUCTeX, a buffer-local minor mode. If it is switched on,
omega
will be used instead of tex
, and
lambda
instead of latex
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AUCTeX allows you to start external programs for previewing your document. These are normally invoked by pressing C-c C-c once the document is formatted or via the respective entry in the Command menu.
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 information about which file types and style options are
associated with which viewers and options for them is stored in the
variables TeX-output-view-style
and TeX-view-style
.
The command TeX-view
, bound to C-c C-v, starts 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
DVI viewer when using TeX-source-specials-mode
.
List of output file extensions, style options and view options.
List of style options and view options. This is the predecessor of
TeX-output-view-style
which does not allow the specification of
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 will be made.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can make use of forward and inverse searching if this is supported
by your DVI viewer and you enabled
TeX-source-specials-mode
. See section Executing Commands, on how to do that.
AUCTeX will automatically pass the necessary command line options to
the viewer in order to display the page containing the content you are
currently editing (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-specials-view-start-server
to
inhibit the question and always or never start the server respectively.
If TeX-source-specials-mode
is active and a DVI 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.
Once the server and the viewer are running you can use a mouse click in the viewer to jump to the corresponding part of your document in Emacs (inverse search). Refer to the documentation of your viewer to find out what you have to do exactly. In xdvi you usually have to use C-down-mouse-1.
For PDF output, forward search is availabe when using the pdfsync
LaTeX package and xpdf as PDF viewer. With the pdfsync package
forward search does not rely on source specials. Therefore you don't
have to bother about the provisions for source specials explained above.
If document parsing is enabled, the functionality is usable immediately,
e.g. by typing C-c C-v (TeX-view
) which will open the
viewer or bring it to front if it is already opened and display the
output page corresponding to the position of point in the source file.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Once you've formatted your document you may `debug' it, i.e. browse through the errors (La)TeX reported.
(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.
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.
(C-c C-t C-w) Toggle whether AUCTeX should stop at warnings as well as normal errors.
As default, AUCTeX will display that 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.
When non-nil AUCTeX will automatically display a help text whenever
an error is encountered using TeX-next-error
(C-c `).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [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 utility lacheck
can be used
to find style errors, such as forgetting to escape the space after an
abbreviation or using ‘...’ instead of ‘\ldots’ and many other
problems like that. You start lacheck
with C-c C-c Check
<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 (emacs)Compilation section `Compilation' in The Emacs Editor), which will move point to the location of the next error.
Another newer program which can be used to find errors is chktex
.
It is much more configurable than lacheck
, but doesn't find all
the problems lacheck
does, at least in its default configuration.
You must install the programs before using them, and for chktex
you may also need modify TeX-command-list
unless you use its
lacheck
compatibility wrapper. You can get lacheck
from
‘<URL:ftp://ftp.ctan.org/tex-archive/support/lacheck/>’ or
alternatively chktex
from
‘<URL:ftp://ftp.ctan.org/tex-archive/support/chktex/>’.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [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
and
ConTeXt-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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
(C-c ?) Get documentation about macros, packages or TeX & Co. in general. The function will prompt for the name of a command or manual, providing a list of available keywords for completion. If point is on a command or word with available documentation, this will be suggested as default.
The command can be invoked by the key binding mentioned above as well as the ‘Find Documentation...’ entry in the mode menu.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Build Daemon user on October, 17 2008 using texi2html 1.78.