TeX is a powerful text formatter written by Donald Knuth; it is also free, like GNU Emacs. LaTeX is a simplified input format for TeX, implemented by TeX macros; it comes with TeX. SliTeX is a special form of LaTeX.
Emacs has a special TeX mode for editing TeX input files. It provides facilities for checking the balance of delimiters and for invoking TeX on all or part of the file.
TeX mode has three variants, Plain TeX mode, LaTeX mode, and SliTeX mode (these three distinct major modes differ only slightly). They are designed for editing the three different formats. The command M-x tex-mode looks at the contents of the buffer to determine whether the contents appear to be either LaTeX input or SliTeX input; if so, it selects the appropriate mode. If the file contents do not appear to be LaTeX or SliTeX, it selects Plain TeX mode. If the contents are insufficient to determine this, the variable tex-default-mode controls which mode is used.
When M-x tex-mode does not guess right, you can use the commands M-x plain-tex-mode, M-x latex-mode, and M-x slitex-mode to select explicitly the particular variants of TeX mode.
Here are the special commands provided in TeX mode for editing the text of the file.
Insert, according to context, either " or " or " (tex-insert-quote).
Insert a paragraph break (two newlines) and check the previous paragraph for unbalanced braces or dollar signs (tex-terminate-paragraph).
Check each paragraph in the region for unbalanced braces or dollar signs.
Insert {} and position point between them (tex-insert-braces).
Move forward past the next unmatched close brace (up-list).
In TeX, the character " is not normally used; we use " to start a quotation and " to end one. To make editing easier under this formatting convention, TeX mode overrides the normal meaning of the key " with a command that inserts a pair of single-quotes or backquotes (tex-insert-quote). To be precise, this command inserts " after whitespace or an open brace, " after a backslash, and " after any other character.
If you need the character " itself in unusual contexts, use C-q to insert it. Also, " with a numeric argument always inserts that number of " characters. You can turn off the feature of " expansion by eliminating that binding in the local map (Section 32.4.)
In TeX mode, $ has a special syntax code which attempts to understand the way TeX math mode delimiters match. When you insert a $ that is meant to exit math mode, the position of the matching $ that entered math mode is displayed for a second. This is the same feature that displays the open brace that matches a close brace that is inserted. However, there is no way to tell whether a $ enters math mode or leaves it; so when you insert a $ that enters math mode, the previous $ position is shown as if it were a match, even though they are actually unrelated.
TeX uses braces as delimiters that must match. Some users prefer to keep braces balanced at all times, rather than inserting them singly. Use C-c { (tex-insert-braces) to insert a pair of braces. It leaves point between the two braces so you can insert the text that belongs inside. Afterward, use the command C-c } (up-list) to move forward past the close brace.
There are two commands for checking the matching of braces. C-j (tex-terminate-paragraph) checks the paragraph before point, and inserts two newlines to start a new paragraph. It prints a message in the echo area if any mismatch is found. M-x validate-tex-region checks a region, paragraph by paragraph. When it finds a paragraph that contains a mismatch, it displays point at the beginning of the paragraph for a few seconds and sets the mark at that spot. Scanning continues until the whole buffer has been checked or until you type another key. Afterward, you can use the mark ring to find the last several paragraphs that had mismatches (Section 11.5).
Note that Emacs commands count square brackets and parentheses in TeX mode, not just braces. This is not strictly correct for the purpose of checking TeX syntax. However, parentheses and square brackets are likely to be used in text as matching delimiters and it is useful for the various motion commands and automatic match display to work with them.
LaTeX mode, and its variant, SliTeX mode, provide a few extra features not applicable to plain TeX.
Insert \begin and \end for LaTeX block and position point on a line between them. (tex-latex-block).
Close the innermost LaTeX block not yet closed (tex-close-latex-block).
In LaTeX input, \begin and \end commands are used to group blocks of text. To insert a \begin and a matching \end (on a new line following the \begin), use C-c C-o (tex-latex-block). A blank line is inserted between the two, and point is left there. You can use completion when you enter the block type; to specify additional block type names beyond the standard list, set the variable latex-block-names. For example, here's how to add theorem, corollary, and proof:
(setq latex-block-names '("theorem" "corollary" "proof")) |
In LaTeX input, \begin and \end commands must balance. You can use C-c C-e (tex-close-latex-block) to insert automatically a matching \end to match the last unmatched \begin. It indents the \end to match the corresponding \begin. It inserts a newline after \end if point is at the beginning of a line.
You can invoke TeX as an inferior of Emacs on either the entire contents of the buffer or just a region at a time. Running TeX in this way on just one chapter is a good way to see what your changes look like without taking the time to format the entire file.
Invoke TeX on the current region, together with the buffer's header (tex-region).
Invoke TeX on the entire current buffer (tex-buffer).
Invoke BibTeX on the current file (tex-bibtex-file).
Invoke TeX on the current file (tex-file).
Recenter the window showing output from the inferior TeX so that the last line can be seen (tex-recenter-output-buffer).
Kill the TeX subprocess (tex-kill-job).
Print the output from the last C-c C-r, C-c C-b, or C-c C-f command (tex-print).
Preview the output from the last C-c C-r, C-c C-b, or C-c C-f command (tex-view).
Show the printer queue (tex-show-print-queue).
You can pass the current buffer through an inferior TeX by means of C-c C-b (tex-buffer). The formatted output appears in a temporary file; to print it, type C-c C-p (tex-print). Afterward, you can use C-c C-q (tex-show-print-queue) to view the progress of your output towards being printed. If your terminal has the ability to display TeX output files, you can preview the output on the terminal with C-c C-v (tex-view).
You can specify the directory to use for running TeX by setting the variable tex-directory. "." is the default value. If your environment variable TEXINPUTS contains relative directory names, or if your files contains \input commands with relative file names, then tex-directory must be "." or you will get the wrong results. Otherwise, it is safe to specify some other directory, such as "/tmp".
If you want to specify which shell commands are used in the inferior TeX, you can do so by setting the values of the variables tex-run-command, latex-run-command, slitex-run-command, tex-dvi-print-command, tex-dvi-view-command, and tex-show-queue-command. You must set the value of tex-dvi-view-command for your particular terminal; this variable has no default value. The other variables have default values that may (or may not) be appropriate for your system.
Normally, the file name given to these commands comes at the end of the command string; for example, latex filename. In some cases, however, the file name needs to be embedded in the command; an example is when you need to provide the file name as an argument to one command whose output is piped to another. You can specify where to put the file name with * in the command string. For example,
(setq tex-dvi-print-command "dvips -f * | lpr") |
The terminal output from TeX, including any error messages, appears in a buffer called *tex-shell*. If TeX gets an error, you can switch to this buffer and feed it input (this works as in Shell mode; Section 31.15.2). Without switching to this buffer you can scroll it so that its last line is visible by typing C-c C-l.
Type C-c C-k (tex-kill-job) to kill the TeX process if you see that its output is no longer useful. Using C-c C-b or C-c C-r also kills any TeX process still running.
You can also pass an arbitrary region through an inferior TeX by typing C-c C-r (tex-region). This is tricky, however, because most files of TeX input contain commands at the beginning to set parameters and define macros, without which no later part of the file will format correctly. To solve this problem, C-c C-r allows you to designate a part of the file as containing essential commands; it is included before the specified region as part of the input to TeX. The designated part of the file is called the header.
To indicate the bounds of the header in Plain TeX mode, you insert two special strings in the file. Insert %**start of header before the header, and %**end of header after it. Each string must appear entirely on one line, but there may be other text on the line before or after. The lines containing the two strings are included in the header. If %**start of header does not appear within the first 100 lines of the buffer, C-c C-r assumes that there is no header.
In LaTeX mode, the header begins with \documentstyle and ends with \begin{document}. These are commands that LaTeX requires you to use in any case, so nothing special needs to be done to identify the header.
The commands (tex-buffer) and (tex-region) do all of their work in a temporary directory, and do not have available any of the auxiliary files needed by TeX for cross-references; these commands are generally not suitable for running the final copy in which all of the cross-references need to be correct.
When you want the auxiliary files for cross references, use C-c C-f (tex-file) which runs TeX on the current buffer's file, in that file's directory. Before running TeX, it offers to save any modified buffers. Generally, you need to use (tex-file) twice to get the cross-references right.
Large TeX documents are often split into several files--one main file, plus subfiles. Running TeX on a subfile typically does not work; you have to run it on the main file. In order to make tex-file useful when you are editing a subfile, you can set the variable tex-main-file to the name of the main file. Then tex-file runs TeX on that file.
The most convenient way to use tex-main-file is to specify it in a local variable list in each of the subfiles. Section 32.2.5.
For LaTeX files, you can use BibTeX to process the auxiliary file for the current buffer's file. BibTeX looks up bibliographic citations in a data base and prepares the cited references for the bibliography section. The command C-c TAB (tex-bibtex-file) runs the shell command (tex-bibtex-command) to produce a .bbl file for the current buffer's file. Generally, you need to do C-c C-f (tex-file) once to generate the .aux file, then do C-c TAB (tex-bibtex-file), and then repeat C-c C-f (tex-file) twice more to get the cross-references correct.
Entering any kind of TeX mode runs the hooks text-mode-hook and tex-mode-hook. Then it runs either plain-tex-mode-hook or latex-mode-hook, whichever is appropriate. For SliTeX files, it calls slitex-mode-hook. Starting the TeX shell runs the hook tex-shell-hook. Section 32.2.3.