Formatting and Printing

The most powerful features of AUC TeX may be those allowing you to run (La)TeX and other external commands like BibTeX and makeindex from within Emacs, viewing and printing the results, and moreover allowing you to debug your documents.

Executing Commands

Formatting the document with TeX or LaTeX, 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.

Command: TeX-command-master

(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 Installation of AUC TeX for a discussion about TeX-command-list and section Multifile Documents for a discussion about TeX-master.

Command: TeX-command-region

(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 not active, 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.

AUC TeX 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 section Catching the errors and section Controlling the output will work on that process, otherwise they will work on the process associated with the current document.

User Option: TeX-region

The name of the file for temporarily storing the text when formatting the current region.

User Option: TeX-header-end

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.

User Option: TeX-trailer-start

A regular expression matching the start of the trailer. By default, this is `\end{document}' in LaTeX mode and `\bye' in TeX mode.

AUC TeX 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.

User Option: 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 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: 

AUC TeX 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, AUC TeX will query before saving each file. By default AUC TeX 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.

Catching the errors

Once you've formatted your document you may `debug' it, i.e. browse through the errors (La)TeX reported.

Command: TeX-next-error

(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 AUC TeX will only report real errors, but you may as well ask it to report `bad boxes' as well.

Command: TeX-toggle-debug-bad-boxes

(C-c C-w) Toggle whether AUC TeX should stop at bad boxes (i.e. over/under full boxes) as well as at normal errors.

As default, AUC TeX 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.

User Option: TeX-display-help

When non-nil AUC TeX will automatically display a help text whenever an error is encountered using TeX-next-error (C-c `).

Checking for problems

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 C h e c k 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 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 must also modify TeX-command-list. You can get lacheck from `<URL:ftp://sunsite.auc.dk/pub/text/lacheck/>' or alternatively chktex from `<URL:ftp://ftp.dante.de/pub/tex/support/chktex/>'. Search for `chktex' in `tex.el' to see how to switch between them.They are

Controlling the output

A number of commands are available for controlling the output of an application running under AUC TeX

Command: TeX-kill-job

(C-c C-k) Kill currently running external application. This may be either of TeX, LaTeX, previewer BibTeX etc.

Command: TeX-recenter-output-buffer

(C-c C-l) Recenter the output buffer so that the bottom line is visible.

Command: TeX-home-buffer

(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.