Hour 17: Editing LaTeX/HTML Files: Writing and Processing LaTeX

Why even bother to learn LaTeX when a word processor offers similar functionality without the bother of markup tags? For a short document such as a letter or memo, a word processor is often more convenient. However, keeping indexes, cross -references, and footnotes synchronized as a document is written can strain the capabilities of a word processor. This is where LaTeX styles and packages come into play. A TeX/LaTeX installation includes a wide variety of predefined styles and optional packages with many more available on the Internet. This enables a writer to concentrate on content, letting the TeX utilities perform the grunt work of constructing a document that is consistently formatted and professional looking.

Getting Started

You can create and edit LaTeX files with Emacs, but to process them you need a functional TeX installation. There are several TeX/LaTeX packages available for just about any operating system, some free and others which cost money. Linux users can install preconfigured packages which are included with most Linux distributions.

Because the files required are large, many people purchase a TeX CD-ROM from a vendor such as Walnut Creek (see their Web site at http://www.cdrom.com).

Most TeX packages include ample documentation, often including the unprocessed LaTeX files; these files can be identified by their .tex suffix, and provide good examples for viewing and experimentation. A particularly useful introductory file is called essential.tex, available at CTAN mirrors such as ftp.cdrom.com; on that North American site it can be found in the directory /pub/tex/ctan/info/latex-essential. essential.tex (or any short LaTeX file) can be used to determine whether your TeX installation is configured properly. At a command prompt, type latex essential.tex; the result should be a file named essential.dvi. By processing this file you have verified that TeX is functional on your machine, and as a bonus you have a very readable and informative beginner's guide to LaTeX.

When you have verified that TeX works for you, load the original essential.tex file into an Emacs session. You should notice that a new menu, TeX, has appeared on the menubar (as shown in Figure 17.5). From this menu you can run the file through the TeX process, creating a DVI file and viewing the file with your DVI viewer. Type C-h-m; a window opens showing the various special keys which this TeX mode offers. Look over the essential.tex file; at the very beginning of this file (and scattered elsewhere) are lines which begin with a % character. These comments are ignored by the TeX parser and do not appear in the output file. Any line beginning with a backslash is a formatting command (or tag) for TeX. Notice the markup tags near the beginning of the file that set the document type and other variables. Scroll farther in the file and you see that paragraphs of the actual text content are relatively free of markup. A blank line signals a new paragraph just as in a word processor.

The default settings, such as the name of the DVI viewer and your printing commands, likely work out of the box on a Linux system.

As with HTML, basic document templates save time when you create a LaTeX file from scratch. essential.tex contains a simple template which can be copied into a new file for this purpose. If you do this, it's a good idea to make one change in the template. essential.tex was written in 1988, when LaTeX version 2.09 was current. Since then, LaTeX has been revised and improved (the current version is LaTeX2e). The essential.tex file uses the obsolete \documentstyle tag; this should be changed in your template to \documentclass.

AucTeX Installation and Basics

The GNU Emacs default TeX mode is useful, but you still have to type the majority of the markup tags. A separately maintained add-on package called AucTeX adds many convenient shortcuts for editing LaTeX files in Emacs. This package is included with XEmacs, but it works equally well with GNU Emacs. If you decide to spend much time writing LaTeX files, it's well worth the time spent obtaining and installing it.

If you use XEmacs, AucTeX should be already installed (but not necessarily configured). GNU Emacs users can obtain the latest version of the package from the WWW site http://sunsite.auc.dk/auctex/ .

The source archive includes a makefile, which needs to be edited in order to adapt the installation to your needs (mainly setting paths, such as the location of your Emacs site-lisp directory and the TeX installation). Typing make install should first byte-compile the Lisp files, using Emacs in its noninteractive batch mode, and then install the files in a newly created auctex subdirectory of your site-lisp directory. The final steps are to edit the /site-lisp/auctex/tex.el file and copy the clearly marked sections that determine the paths to a new file, /site-lisp/tex-site.el. Edit this file so that it accurately reflects the actual locations of your TeX directory and your Emacs AucTeX directory. Then append to your .emacs file the following line:

The next time you start up Emacs and load a .tex file you see new items on the menubar. Instead of a single TeX menu, you see both a LaTeX and a Commands menu. Numerous commands are on these menus, most of which are relatively self-explanatory (read the AucTeX info files, which come with the distribution). As a demonstration of the convenience of this package, open a new empty LaTeX file called trial.tex, by typing C-x-C-f and, when prompted in the minibuffer, type trial.tex. AucTeX should be loaded automatically. Confirm this by seeing whether the two new items mentioned appear on the menubar. If AucTeX fails to load, make sure you have correctly modified your .emacs file, and recheck the settings in the new tex-site.el file.

Pull down the LaTeX menu, select Insert Environment (as shown in Figure 17.6), and choose the topmost of the three alphabetically arranged submenus. Select Document as the environment to be inserted into the file. The keybinding for Insert Environment is C-c C-e. When using this keybinding, you are prompted in the minibuffer for the type of environment with a default choice suggested.

A environment in a LaTeX document is a set of tags surrounding an area of text that specifies how it should be formatted. In this case, the Document environment is the entire file. Every document needs to belong to one of several available document classes; the class can be book, letter, article, report, or slide.

Tags and Keys

AucTeX has a well-designed set of keybindings which simplify entering tags. For example, C-c C-s enters an appropriate section tag. You are prompted in the minibuffer for the type of section as well its name and label; the default choice offered for the type of section depends on the type of document you are editing. The label is used internally for cross references and indexing.

Various types of lists, both numbered and ordinary, are easily included in a LaTeX file. Look at the third submenu under LaTeX, Insert Environment; select Itemize and you should see this tagging in your file:

The cursor is placed right after \item, making it easy to type your item's content. Type a word or two and press M-Enter. A new item tag is inserted. The enumerate tag is a variation that sequentially numbers the items in the output. The numbers don't need to be included in the LaTeX file, because the TeX programs automatically put them in.

Another commonly used group of tags is used to change the font of a word or region. The keybindings for these tags all begin with C-c C-f:

C-c C-f C b	inserts the Bold tag
C-c C-f C e	inserts the Emphasize tag
C-c C-f C t	inserts the Typewriter tag (a monospaced like Courier)
C-c C-f C c	inserts the Small Caps tag (all capitalized in a small font)
C-c C-f C f	inserts the Sans Serif tag (a font like Helvetica)
C-c C-f C I	inserts the Italic tag
C-c C-f C s	inserts the Slanted tag (similar to italic)
C-c C-f C r	inserts the Roman tag (a font like Times New Roman)
C-c C-f C a	inserts the Calligraphic tag

Try typing one of the more commonly-used tags-- C-c C-f C i, used for italic text. You see this in your buffer:

Anything typed within the pair of curly braces of this tag is italicized in the final output.

The LaTeX menu can also be used for these tags. They can be found as submenus under the Insert Font, Change Font, and Delete Font items.

The Command Menu

Next to the LaTeX menu is the Command menu. Here you find commands for processing a LaTeX file from within Emacs. The most useful item on this menu when writing LaTeX files is LaTeX Interactive. Try it out either by loading a finished LaTeX file or by writing one yourself. Select LaTeX Interactive from the Command menu, and your Emacs window splits horizontally. The bottom half of the screen displays the verbose output of the TeX engine as it processes the file. It should complete successfully, as indicated by the statement Output written on filename.dvi (as shown in Figure 17.7).

If any serious errors appear, the line number is indicated in the output window. AucTeX provides a convenient method of stepping through errors that might occur. An item in the LaTeX menu, Next Error, moves forward in the file to each successive error when you finish fixing the problem. C-c-' is the keyboard equivalent.

When you have processed the file and no errors are being reported, select View from the Command menu. A message appears in the minibuffer, showing you the command that is run if you press Enter. The default DVI viewer is xdvi; if yours has a different name, edit the command before pressing Enter. The name of the default viewer should be changed using Customize if you use AucTeX often.