Most typewriters and many word processors use the same symbol for opening and closing quotations. You are probably used to typing the double-quote key to insert quotation marks into your text. However, if you look carefully at TeX output (or any professionally typeset document) you will notice that the opening and closing quotation marks do not look the same. The proper way to type an opening quote (“) in TeX is with two single back-quotes in a row (``). A closing quote (”) is entered with two single quotes (apostrophes) in a row (''). This process is tedious and error-prone since you are used to typing something else.

If you accidentally use the double quote symbol in your input, you most frequently get text that looks like ”this.” The exact result is actually dependent upon the font you are using. This is explained in Chapter Chapter 5, Chapter 5. Most programmable editors can change the meaning of the double-quote key to insert the correct quotation marks.

If you are interested in programming your editor to do this, you can use the following algorithm to select the correct quotation marks most of the time: if the character to the immediate left of the cursor is a space, opening brace, parenthesis, or bracket, insert opening quotes; otherwise, insert closing quotes. As a further enhancement, double quotes should be inserted immediately following a backslash.

Braces, as mentioned in Chapter Chapter 1, Chapter 1, are used by TeX to delimit sections of text; they appear often in TeX documents. GNU emacs, Multi-Edit, and Brief can all be programmed to highlight the matching open brace whenever you type a closing brace.

For example, if you have entered the text

\footnote{This is {\it not} the only case.}

and the next character that you type is }, the open brace immediately following the word \footnote is highlighted, or all of the text between that brace and the current cursor position is highlighted. This feature makes it easier to find places where you have forgotten to insert a closing brace.

If you usually work in “insert” mode, you may also find it convenient to have the editor insert braces in pairs and then insert text between them. This can be accomplished in almost any editor that can be programmed, even one that isn't equipped to handle brace matching.

Most editors can be programmed to insert arbitrary text when a special key is pressed. This feature can be used to insert common control sequences. For example, you might have Alt-c insert the \chapter control sequence or Ctrl-e insert \begin{enumerate}.

One of the nicest features that an editor can provide is the ability to run TeX automatically without leaving the editor. This is a feature that programmers demand because it allows them to run compilers directly from the editor. Editors that provide this feature usually include some mechanism for programming the editor to locate the position of errors reported by the compiler. The editor searches for error messages in the output generated by the compiler, and it positions the cursor at the location of each error. This speeds up the traditional edit/compile/debug cycle of programming. You can take advantage of these features to shorten the edit/typeset/rewrite cycle of creating a TeX document.

All of the editors discussed in this chapter can easily be adapted to run TeX in this way. If you already have a favorite editor and want to add this functionality for TeX, see the section “the section called “Running TeX”” later in this chapter; it describes the process at a very general level.

GNU emacs provides two similar TeX editing modes: one designed for editing Plain TeX documents (plain-tex-mode) and the other for editing LaTeX documents (latex-mode). The latex-mode is a superset of plain-tex-mode that provides additional shortcut keys for some LaTeX control sequences.

There are three ways to start TeX mode in GNU emacs:

If you use M-x tex-mode, emacs examines the top of the buffer in order to select the appropriate mode. If the control sequences \documentstyle or \begin{document} occur near the top of the buffer, latex-mode is selected; otherwise, the default mode is selected. The default mode is stored in the emacs lisp variable TeX-default-mode.

You can also tell emacs to invoke TeX mode automatically whenever you edit a file that has a name ending in .tex. To do so, add the following lines to your emacs startup file, usually called .emacs in your home directory:^[18]

(setq auto-mode-alist (append '(("\\.tex$" . tex-mode))
                               auto-mode-alist))

The emacs TeX modes change the meaning of several keys to provide features useful for editing TeX documents. These special key bindings apply only to buffers that you edit while emacs is in plain-tex-mode or latex-mode.

Automatic quotation, brace balancing in paragraphs, inserting brace pairs, skipping over unmatched braces, and closing open environments are supported.

When TeX typesets your document, it produces processing and error messages. By running TeX for you, emacs can capture these messages and display them in a window. You can use this feature to help locate and correct errors.

Functions that run TeX from inside the editor rely on emacs' ability to run a subshell. Some implementations of emacs, particularly implementations for MS-DOS, which is unable to run concurrent processes, cannot use this feature. aucTeX, a different editing environment for GNU emacs, does allow you to use these features with MS-DOS ports of GNU emacs. (aucTeX is described in the next section.)

GNU emacs supports processing of both buffers and regions. These modes don't locate errors for you automatically, but they do place the output from TeX in an emacs buffer so that you can find them yourself. Chapter Chapter 3, Chapter 3, describes how to interpret TeX output and find the location of errors.

The instructions provided with each release of aucTeX describe how to build and install the software so that aucTeX will automatically be invoked when you edit a file with a name ending in .tex.

If you think aucTeX is already installed on your system (because the emacs Info page for it is present, for example), ask your system administrator where it is installed. One common location is /usr/local/lib/emacs/site-lisp/auctex.

Adding the following line to your emacs startup file (typically .emacs in your home directory) will load aucTeX each time you start emacs:

  (load-file "/path/for/auctex/tex-site.elc")

aucTeX provides a large number of typing shortcuts. Many of the keystroke shortcuts are designed specifically to aid in typing LaTeX documents. In addition to command keys, aucTeX provides another typing shortcut---command completion for LaTeX control sequences with C-c TAB.

If you type a backslash followed by the beginning of a control sequence name into a buffer and then type C-c TAB, aucTeX completes as much of the control sequence as possible. Every time aucTeX adds another letter to the control sequence name, it compares the resulting name to a configurable list of LaTeX control sequences. If it reaches a point where the control sequence could be continued in two different ways, it stops and displays all the possible completions. For example, there are two control sequences in standard LaTeX that begin with \re: \renewcommand and \renewenvironment.

If you type:

\re C-c TAB

aucTeX will insert new because that much of the control sequence name can be deduced from the known possibilities. This changes the text in your document to:

\renew

Because aucTeX cannot figure out which of the possibilities you want, it displays a list of the LaTeX commands that begin with \renew. You can complete the command by typing c or e and pressing C-c TAB again. If you want the \renewcommand function, type:

\renewcC-c TAB

Now, aucTeX will insert ommand and return to normal typing mode with the cursor positioned just after the control sequence name:

\renewcommand _

aucTeX has special support for LaTeX sectioning commands and environments, changing fonts, commenting out sections of a document, reformatting the input text, and entering mathematics.

TeX contains a lot of support for typesetting mathematics. In that spirit, aucTeX provides a minor mode^[21] for entering mathematical formulae.

In mathematics minor mode, pressing ` changes the meaning of the next character you type. The next character is interpreted as an abbreviation for a mathematical symbol or function. For example, in aucTeX, typing

inserts

$α \leq β$

into your document (which is typeset like this: α≤β).

Table  Table 2.1 lists all of the abbreviations. The first column of the table displays the shortcut keys. The second and third columns show the command inserted in your document and the typeset symbol, respectively .

Additional miscellaneous commands in aucTeX provide automatic quotation, completion of “items” in appropriate environments (itemize and enumeration environments, for example), and insertion of brace pairs and skeletal control sequences.

Outline mode is a convenient way to edit large documents. In outline mode, portions of the document that you are not editing are hidden from view. They aren't removed or deleted. Emacs indicates hidden text with ellipses.

For example, in a large document with many sections, you can use outline mode to hide all text except the section headings, and then selectively expand just the sections that you wish to edit.

aucTeX understands the TeX constructions for many kinds of environments (the list environments, for example) and performs paragraph reformatting within the restrictions of these environments. aucTeX won't concatenate a whole series of list items together into one huge paragraph, for example.

It is often convenient to edit a large document in small pieces rather than in one huge file. For example, when writing a book, it is convenient to work on chapters independently and store them in different files. If you are working on a collaborative project, it may be absolutely necessary to separate the document into pieces.

The TeX \input command allows you to construct a driver file that automatically combines the individual files that make up your document when you run TeX. The driver file contains the document style options and other setup information for the whole document. Each chapter contains just the necessary text. When TeX encounters an \input command, it typesets all of the text in the specified file before continuing with the current document. Example Example 2.1 shows an example of a driver file.

\documentstyle[ora]{book}
\begin{document}
   \input{intro}
   \input{chap1}
   \input{chap2}
\end{document}

aucTeX provides seamless support for multi-file documents. In order to provide this support, aucTeX relies on the “file variables” feature of emacs, which allows you to associate editor variables with particular buffers. An editor variable is a named variable that is local to the current buffer and accessible by macro packages like aucTeX running under emacs. Look up file variables in your emacs reference for a more complete description. Example  Example 2.2 shows some common local variables in aucTeX.

When you run TeX on a buffer, aucTeX looks for the editor variable TeX-master. If TeX-master is set to a filename, aucTeX runs TeX on that file instead of running it directly on the file you are editing. This is a tremendously useful feature because it means that you do not have to put macro definitions, document style options, and other setup information at the top of each chapter. Simply set the TeX-master variable in each chapter to name the driver file.

If you do not set the TeX-master variable, aucTeX will prompt you for it the first time you run a command. If the \documentstyle command occurs near the top of your document, aucTeX assumes that the current buffer is the master (because it contains setup information) and will not prompt you for a different master file.

Editor variables are defined by a “Local Variables” declaration at the bottom of your file. aucTeX inserts a Local Variables declaration automatically if it prompts you for a master file. Example  Example 2.2 shows how local variables TeX-master and TeX-command-default can be set to driver.tex and LaTeX, respectively. Because these lines begin with a percent sign, they are considered comments by TeX and do not appear in the output. These should be the last lines in the file.

% Local Variables:
% TeX-master: "driver.tex"
% TeX-command-default: "LaTeX"
% End:

Like GNU emacs TeX mode, aucTeX allows you to run TeX directly from within emacs as a subshell. Running a program inside emacs creates a process. You can have only one active process for each document, plus one process for TeXing a region. If you try to run two processes on the same document, aucTeX will ask for permission to kill the first before running the second. aucTeX supports the processing of both the documents and the regions of a document.

No matter how much experience you have with TeX, some of the documents that you write will contain errors. aucTeX eases the burden of correcting these errors by locating them automatically in your document.

Support for TeX is included as a language type in Multi-Edit. Language types are selected by filename extension; this means that you configure Multi-Edit to provide support for the “TeX language” whenever you edit files with the extension .tex (and other extensions if you choose).

Selecting the “Other/Install/Filename extensions...” menu displays a list of configured extensions. If TEX is not listed, press Insert to add it. You will see a screen like the one shown in Figure  Figure 2.1.

Figure 2.1. Extension setup in Multi-Edit

Customize the right margin, tab spacing, indent style, and colors to values that you find comfortable. The edit mode should be “text,” and the tab settings should be set to “use tab and margin settings, ignore format line.”

Select TEX as the language type, and add TeX as a compiler. One possible setting for TeX as a compiler (for LaTeX documents, in this case) is shown in Figure  Figure 2.2.

Figure 2.2. LaTeX as a compiler in Multi-Edit

Brace matching is provided automatically with Multi-Edit's template expansion support. Consult your Multi-Edit reference for more information about templates.

Multi-Edit language support does not include any TeX key bindings by default. However, the macros are provided, and you can install them with the “Other/Install/Key mapping...” menu. The following macros are available:

Running TeX within Multi-Edit is accomplished by specifying a compiler for TeX or LaTeX documents. In Figure  Figure 2.2, a batch file called TEXIT is being used as the compiler for documents with the extension .tex.

Automatic compilation and location of errors is provided by Multi-Edit language support when you have selected TEX as the language-type for .tex files.

Establish the TeX program as a compiler using whatever features your editor provides to set up a compiler. Experiment with your editor until you can process an error-free document.

After you have everything working, it may be desirable to modify the compiler to run a batch file or shell script instead of invoking the TeX program directly. This will allow you to program the shell script so that it can determine which format file to use.

Running TeX is only the first step. Next, you have to interpret the error messages that TeX produces. As a concrete example, Example Example 2.3 shows some contrived output which demonstrates an “undefined control sequence” error on line 6 of the file wilma.tex.

This is TeX version 3.141...
** (flintstone.tex
some
messages [1]
(fred.tex [2]
some more
messages
[3] ) (wilma.tex [4]
! Undefined control sequence.
the dog \dino
              tipped over the car.
l.6 the dog \dino tipped over the car.

Here are some suggestions for attacking the problem of programming your favorite editor to process TeX error messages:

ispell is a common unix spellchecker. In addition to being available from the shell prompt, GNU emacs includes an ispell-mode that handles TeX documents intelligently.

amSpell is an MS-DOS spellchecker that includes special support for TeX documents. When spellchecking a TeX document, amSpell ignores all TeX control sequences, as well as mathematics and the arguments to reference and citation commands. The standard accent primitives are also recognized, and amSpell can identify and correct misspellings in words that use them.

An example of amSpell checking a document is shown in Figure  Figure 2.7.

Figure 2.7. Spellchecking a document with amSpell

TeXShell was designed as an add-on for emTeX (it installs directly into the emTeX directory hierarchy). This character-based interface is available for both MS-DOS and OS/2. TeXShell provides an editor, a complete help system, and fully customizable push-button access to TeX. An example of the TeXShell interface is shown in Figure Figure 2.8. The default TeX menu and help windows are shown.

Figure 2.8. TeXShell

TeXPert is a character-based shell for TeX. MS-DOS and OS/2 versions of TeXPert are available in either German or English. The default configuration files for TeXPert are designed to work with emTeX, but TeXPert does not install directly into the emTeX directory heirarchy. The TeXPert interface is shown in Figure Figure 2.9.

Figure 2.9. TeXPert

TeXPert provides an editor, an archive tool for speedy access to commonly used files, and an interface to grep for quickly scanning files. The exact look and feel of TeXPert can be customized.

The 4TeX system uses the 4DOS extended batch language and a number of utilities to integrate emTeX with a wide variety of free, shareware, and commercial tools. The system is well documented in a manual that describes installation, setup, use, and customization. The 4TeX interface is shown in Figure Figure 2.10.

Figure 2.10. 4TeX

PMTeX is an OS/2 presentation manager program. Although it does not provide a built-in editor, it can control four independent DOS and OS/2 sessions, one each for editing, TeX processing, previewing, and printing. The options passed to each program can be controlled from the PMTeX Options menu.

PMTeX was designed to work with emTeX, but can be configured to use any TeX system. PMTeX was also designed to support two preprocessors for phonetic transcription: the TeuTeX-P and ALDTeX-P scanners. These scanners are useful in dialectology and are available separately from PMTeX's author.

A example of the PMTeX interface is shown in Figure Figure 2.11. Note that the menu bar is very wide and does not fit in a standard 640x480 VGA window.

Figure 2.11. PMTeX

The TeXit shell (which I wrote) is much less ambitious in many ways. Written entirely in Perl, TeXit does not offer a full screen interface or an editor at all. Instead, it provides a simple menu of choices as shown in Figure Figure 2.12 (all of the menu choices are completely customizable).

Processing: ./driver.tex
Again? [?]status, [T]eX & View, [b]ibtex, [c]leanup, 
       [e]dit a file, [p]rint, [q]uery printer, [t]ex, 
       [v]iew, e[x]it:

One of TeXit's strengths is its ability to parse the log file created by TeX and to determine when additional actions are required. For example, TeXit will recognize when a document contains unresolved references and citations and can automatically run BibTeX and repeatedly run TeX to resolve the references. With the addition of a few “user specified” rules in the document, TeXit can easily handle index construction and other more sophisticated relationships.