Making TeX Work

Chapter 3. Running TeX

The heart of processing a document with TeX is running the TeX program. In this chapter, you'll learn what happens between the time you first start the TeX program and the time it finishes. You'll also learn what files TeX really needs (in addition to your document) and what to do when TeX finds things in your document that it doesn't understand.

What Do You Run?

The first thing you have to know is what program to run. Unfortunately, the actual file you have to execute varies between platforms and implementations. If you have built and/or installed TeX yourself, you probably already know what program to run. You'll have to ask your system administrator for help if you can't figure out what the name of the TeX executable is on your computer. The rest of this chapter assumes that the command tex runs TeX. You should substitute the name of the executable program on your own system for tex in the examples that follow.

Most implementations of TeX have some hard-coded memory limits. These limitations may cause problems if you are trying to run a very complex document through TeX. To combat this problem, some distributions include two versions of the TeX executable. One version is a “small” TeX that generally runs faster but has less memory available to process your documents. The other version, a “big” TeX, can process more complex documents but may run more slowly. If you get a “TeX capacity exceeded” error, and you have a big TeX available on your system, try processing your document with the big TeX.

If you still get an error, you have a document that is simply too complex for your implementation of TeX to handle, or you have an error in one of the macros in your document. By examining the error log, described later in this chapter in the section “the section called “Log Files”,” you can determine what macro TeX is interpreting when the error occurs. If the error occurs in a macro that you wrote, check to make sure the macro functions the way you intended by using it in a small test document.

What Files Does TeX Need?

Naturally, TeX needs your input file in order to process it. However, TeX must be able to find several other files as well. The files that TeX needs are normally created during the installation process. Here is a common directory layout for TeX on a unix system:

/usr/local/lib/tex/formats	Format files
/usr/local/lib/tex/pool	Pool files
/usr/local/lib/tex/formats	Format files
/usr/local/lib/tex/inputs	“System” input files
/usr/local/lib/tex/macros	(styles, macros, and miscellaneous
/usr/local/lib/tex/lib	files distributed with TeX)
/usr/local/lib/tex/ps	PostScript support files
/usr/local/lib/tex/fonts/pk	PK fonts
/usr/local/lib/tex/fonts/vf	Virtual fonts
/usr/local/lib/tex/fonts/tfm	TFM metrics

A similar layout is frequently used on other operating systems, except that the TeX files are often stored in a top-level directory (for example, C:$\$TEX under MS-DOS). Because TeX is very flexible and has many different implementations, the exact directory structure varies. Pool files are sometimes placed in the format file directory (which is sometimes called fmt or fmts, rather than formats). Input files may occur in one or more of the standard places listed above (inputs, macros, and lib) as well as a number of other places (texinputs is another common name).

The files under the TeX tree usually come from outside distributions, so you don't have to change them often. (You definitely shouldn't put your personal macro files in that tree, even if you do have access to it.)

The following sections describe, in more detail, each of the files that TeX needs.

Pool Files

Pool files contain string constants used by TeX at runtime. Each time TeX is compiled, it creates a pool file unique to the version being compiled. The pool file from one version of TeX will not work with a different version.

In contrast to format files (discussed in the next section), if you don't have a pool file, there's nothing you can do about it. If you obtained precompiled programs (from the Internet, from a friend, or commercially) and you don't have a pool file, you received an incomplete distribution.

If you did not install TeX yourself, but find that the pool file is missing, contact the system administrator who performed the installation. He or she did something wrong.

Format Files

As mentioned in the section “the section called “Boxes and Glue”” in Chapter 1, Chapter 1, all of the control sequences and macros that your document uses must be defined somewhere. One way to do this is to use the \input command to load all of the definitions at the beginning of each document. However, with large macro packages like LaTeX, this process can be very time consuming. Format files are a way of predefining control sequences and macros so they don't have to be interpreted by TeX every time they're used. If TeX didn't use format files, you'd have to wait for TeX to interpret all of LaTeX every time you processed a document that used LaTeX.

Format files are created by a special version of TeX, usually called iniTeX. Some implementations combine TeX and iniTeX into one program. In this case, you must select iniTeX with a special option when you run TeX. IniTeX interprets all the control sequences in a macro package and builds the in-memory data structures that the TeX program needs. After loading the whole macro package, iniTeX writes the memory image it has constructed to a format file. When TeX later loads the format file, it simply copies it into memory; no interpretation is necessary. This is why loading a format file is such a fast way to define control sequences. This is also why format files are not usually portable from one system to another,^[25] or even between different versions of TeX on the same system. Different versions of TeX are stored differently in memory, and this difference in loading makes the format files incompatible. For this reason, you need a “big” iniTeX to make format files for a big TeX and a “small” iniTeX for a small TeX.

You will find a complete discussion of macro packages and instructions for building format files for many of the common macro packages in Chapter 4, Chapter 4.

User Files

When you run TeX, you have to tell it what file to process. If you specify a complete pathname, TeX will load the specific file that you request. For example, I could process the document myreport.tex in the directory /home/norm/tex/ by running:

\$ tex /home/norm/tex/myreport

This example applies to both unix and PC implementations of TeX. Even though MS-DOS and OS/2 typically use the backslash to separate directory names, always use a forward slash when entering filenames for TeX.

If you specify a simple filename without a path, TeX looks for the file in several user-defined and, possibly, system-defined locations. In the following example, TeX will attempt to locate the file myreport.tex in order to process it:

\$ tex myreport

If the file myreport.tex exists in several directories, TeX will process the first file it finds without looking for any others. TeX always prints the complete name of the file it processes both on the display and in the log file, so you can always tell what file was really processed.

The most common way to specify user-defined locations is by setting the TEXINPUTS environment variable^[26] to a list of subdirectories where TeX documents are kept. Setting TEXINPUTS specifies where TeX should look for documents (files that you input with \input or some other construct, style files, and macros). To change where TeX looks for other kinds of files (fonts, formats, pool files, etc.), setting different environment variables or performing some other customization is required. The format of the environment variable differs according to the platform you use. On unix systems, it is a list of directory names separated by colons. Here is a typical example:

.:/usr/local/lib/tex/inputs:/home/norm/tex/inputs

On MS-DOS and OS/2 systems, it is a list of directory names separated by semicolons. A typical example looks like this:^[27]

.;\tex\inputs;\tex\styles;\tex\macros

Consult the documentation for your particular implementation of TeX for more information about system-defined locations where TeX looks for input files. Unfortunately, this is not always well documented. For example, an undocumented feature of version 1.4s of emTeX always searches in the directory \emtex\texinputs even if it does not occur in the TEXINPUTS path. In fact, there is no way to tell it not to look there, short of renaming the directory (which is what I did).

If TeX cannot find a file you specify, for example rpt-data.tex, it displays a prompt like this one:

! I can't find file ‘rpt-data.tex’.
<*> \input rpt-data

Please type another input filename:

The general form of TeX error messages is discussed in the section called “the section called “What About Errors?”” later in this chapter. TeX announces an error by printing the error message on a line that begins with an exclamation mark. Below the error, TeX provides the context in which the error occurred. In the example above, TeX encountered the command \input rpt-data and tried to find the file rpt-data.tex which it could not locate.

Notice that TeX automatically added the extension .tex to the name of the file it was looking for. In any context where you specify a filename, TeX will append .tex unless you specify an alternate extension.

TeX responds to a “can't find file” error by asking you to type the name of a different file. Some implementations of TeX allow you to abort by typing Ctrl-C or Ctrl-D at this point,^[28] but other implementations insist that you enter a filename. In this case, you'll find it convenient to create an empty file called nul.tex in a directory in your TEXINPUTS path so you can get around this requirement by supplying a dummy answer to the prompt. nul.tex is part of many standard distributions.

The Command Line

Except for the name of a document, TeX has very few command-line options. The only option that is regularly used is the name of a format file, but the use of this option is frequently buried inside a batch file or shell script.

It is helpful to think of TeX, LaTeX, SliTeX, etc. as different text processors (they aren't really; they're all TeX with different format files). This illusion is easy to provide with shell scripts or batch files. For example, on an MS-DOS system, you could easily have three batch files called tex.bat, latex.bat, and slitex.bat:

• The tex.bat file runs the TeX executable with the plain format file specified as an option.
• The latex.bat file runs TeX with the lplain format file.
• The slitex.bat file runs TeX with the splain format file.

Now typing tex filename processes Plain TeX documents; typing latex filename processes LaTeX documents; and typing slitex filename processes SliTeX documents.^[29] The role of format files and macro packages is described fully in Chapter 4, Chapter 4.

Command-line Options

A formal specification of the TeX command line looks like this:

$ tex <switches> <&format> <|document> <tex-commands>

If this looks confusing, have no fear. I'll explain what it means in English.

After the name of the TeX program (or batch file), the first things that can go on the command line are implementation-dependent switches and options. For example, implementations of TeX that combine iniTeX and TeX into a single program may use /I as the switch to specify that iniTeX processing is desired (iniTeX, you may remember, was described in the section “the section called “What Do You Run?”,” earlier in this chapter). There are no system-independent switches for TeX. Consult the documentation that comes with your implementation for more information about system-dependent switches.

After any system-dependent switches, the first thing that you can put on the TeX command line is the name of the format file to use. If you specify this option, you must include it before any other options, and you must put an ampersand (&) in front of the format file name. If you do not specify a format file, TeX will use a default format, usually Plain TeX.

After the format, TeX looks for the name of a document to process. If TeX finds a filename on the command line, it will process the document contained in that file before looking at any other options that may follow.

Finally, you can insert arbitrary TeX commands on the command line by typing them just as you would in a document. The section “the section called “Running TeX”” in Chapter 2, Chapter 2, describes one particular instance where this is very useful, but it isn't something that you are likely to do very often.

Command-line Cautions

There are some special restrictions on file names used on the command line and on the way TeX interprets the command line. These restrictions are summarized here.

Misinterpretation of the command line

Command lines that are typed at the operating system prompt are actually seen by your operating system's “command processor” before they are seen by TeX. You must be aware of special processing that might be performed by the command processor. Under unix, for example, the backslash is frequently interpreted as a shell escape character, and the ampersand has another special meaning related to job control. The ampersand is also special under some MS-DOS and OS/2 command processors where it is the default command separation character and will not be passed to TeX as you would expect.

To insert these troublesome characters literally, you must enclose the relevant sections of the command line in quotation marks or use some form of shell escape mechanism. Under unix, place the name of the format file, including the ampersand, in double or single quotes and use two backslashes in a row if you include TeX control sequences on the command line. For example, type:

$ tex '&lplain' \\nonstopmode \\input doc1

instead of

$ tex &lplain \nonstopmode \input doc1

When using OS/2, place a ^ in front of an ampersand to prevent it from being interpreted as a command separator.

Filenames and TeX

It is easy for TeX to recognize the presence of a format file on the command line; it must be the first option and it must begin with an ampersand.^[30] After the format file, TeX determines whether the next option is a file name by looking at the first character of the option. If the first character is not a backslash, it is a filename; otherwise it is a TeX command, and TeX assumes that no filename is present.

On some systems, notably MS-DOS and OS/2, the backslash is used to delimit the subdirectory components of a file name. On other systems, a forward slash is used. Regardless of the system you use, filenames passed to TeX must use forward slashes to delimit filenames.

For example, TeX will not process the file letter.tex in the \tex\docs directory of the current drive if you execute the following command line on an MS-DOS system:

\$ tex \tex\docs\letter

Instead, you must type the following, regardless of the operating system you're using:

\$ tex /tex/docs/letter

If you don't, TeX will complain that the control sequence \tex is undefined. Even more confusing errors may result if the first subdirectory happens to be a valid control sequence.

Unfortunately, filenames containing forward slashes are not always recognized by operating systems that use backslashes to delimit filenames. For example, under MS-DOS, IF EXIST C:/CONFIG.SYS returns false, even when a file called config.sys exists in the root directory of drive C:. Therefore, it is most convenient to use filenames with backslashes when other commands will be used (for example in a batch file). Filenames in batch files must have any backslashes translated into forward slashes before being passed to TeX. MS-DOS's command processor isn't really powerful enough, but the task is quite doable with JP Software's 4DOS command processor. 4DOS is a replacement for MS-DOS's normal command processor; it offers many advantages over the normal processor. You can get a shareware version of 4DOS from many large MS-DOS archive sites on the Internet^[31] as well as most large bulletin board systems. The following lines, written in 4DOS's extended batch language, will translate all backslashes in the environment variable TEXFN to forward slashes:

:FixBacks
  Set Count=%@Index[%TexFn,\]
  If "%Count" eq "-1" Goto FixDone
  Set Place=%@Eval[%Count+1]
  Set TexFn=%@SubStr[%TexFn,0,%Count]/%@SubStr[%TexFn,%Place]
  Goto FixBacks
:FixDone

These lines also work under OS/2 with JP Software's 4OS2 command processor (akin to 4DOS; shareware versions of 4OS2 are also available). The same task can be completed in a single line with REXX under OS/2:

TEXFN = TRANSLATE(TEXFN, '\', '/')

REXX is an interpreted systems-programming language distributed with OS/2. REXX runs under many other IBM operating systems in addition to OS/2. Several versions of REXX are available for MS-DOS and unix systems, too.

Multiple documents

Keep in mind that TeX interprets only the first option after the format file name as a document name. If you type the command line:

\$ tex doc1 doc2

TeX will process only doc1.tex as a document. The result of the above command line will be exactly as if you had typed the literal word “doc2” at the very end of the file doc1.tex.

To get TeX to process both doc1 and doc2 as documents, type a command like the following:

\$ tex doc1 \input doc2

or, for complete clarity,

\$ tex \input doc1 \input doc2

In either case, the structure of your document files must allow them to be concatenated together. TeX does not process doc1 and then process doc2 separately. Instead, it processes all of doc1 and appends the text in the file doc2 directly onto the end of doc1.

TeX Without Options

If you run TeX without specifying any options at all, it prints out some introductory information, then produces a ** prompt and stops. Here's what emTeX's tex386 produces:

This is emTeX (tex386), Version 3.141 [3c-beta8]
**

This is the only situation where the ** prompt occurs. TeX now expects you to enter text. TeX will interpret anything you type after the ** prompt exactly as if you had typed it on the command line. All of the rules regarding slashes (described in “the section called “Misinterpretation of the command line”” earlier) apply to commands that you type at the ** prompt. Remember, however, that input entered at the ** prompt is not seen by the operating system, so don't use quotation marks or doubled backslashes.

The last line of a document is usually a command telling TeX that the document is finished. TeX responds by writing the last page of the document and ending (returning control to the operating system). If a document doesn't end with such a command, TeX will wait for more input. When TeX runs out of input, it displays the * prompt (single asterisk). Anything you type at the * prompt is interpreted exactly as if it occurred in the document that TeX was processing. You cannot specify an alternate format or name a document at the * prompt. You can, however, use \input to insert another file.

If emTeX processes a document called unended.tex:

% This is UNENDED.TEX
Now is the time for all good men
to come to the aid of their country.
% Note: there's no \bye command to end
% TeX's processing...

the following output appears on the terminal:

This is emTeX (tex386), Version 3.141 [3c-beta8]

**unended
(unended.tex)
*

You can exit from the TeX program at the * prompt by telling TeX that it should stop processing the current document. Exactly how you get out depends on the format file you use. The following table shows the stop commands for some TeX macro packages.

Table 3.1.

Package	Command
Plain TeX	\bye
LaTeX	\end{document}
SliTeX	\end{document}
Lollipop	\Stop
TeXinfo	@bye

If you do not know which format is in use, you can almost always get out with the following steps:^[32]

1. Type a control sequence that TeX will not recognize (control sequences \undefined and \gobbledygook will work). TeX will respond with the question mark prompt.
2. Enter x at the prompt. The question mark prompt is discussed fully in the section “the section called “Interpreting TeX Error Messages”,” later in this chapter.

To continue the above example, if I type \undefined at the * prompt, TeX will respond:

This is emTeX (tex386), Version 3.141 [3c-beta8]
**unended
(unended.tex)
*\undefined
! Undefined control sequence.
<*> \undefined

?

If I enter x at the question mark prompt, TeX will print several informative messages and then end, returning control to the operating system.

This is emTeX (tex386), Version 3.141 [3c-beta8]
**unended
(unended.tex)
*\undefined
! Undefined control sequence.
<*> \undefined

? x
No pages of output.
Transcript written on unended.log.

One word of caution: some macro packages redefine the meaning of the backslash (\) character so that it doesn't function as the beginning of a control sequence (for example, the TeXinfo format uses the at-sign, “@”). In this case, you must precede the undefined control sequence by the escape character, even if it isn't the backslash.

What About Errors?

When you write TeX documents, you will occasionally make mistakes and as a result, TeX won't be able to process your document. There are six broad classes of mistakes you're likely to make:

1. Naming documents or files that TeX cannot find.
2. Misspelling the name of a TeX control sequence.
3. Failing to close an environment or forgetting to insert a closing brace after an opening brace.
4. Using math operators outside of math mode or forgetting to close an opened math environment.
5. Requesting a font that TeX cannot find.
6. Everything else.

TeX is legitimately criticized for having error messages that are very difficult to understand. TeX frequently provides far more information than you really need or want, and the excess information often obscures the actual cause of the error.

Nevertheless, understanding what TeX does when it encounters an error will help make error messages easier to understand. Let's begin with an example. Example 3.1 shows a simple LaTeX document using the New Font Selection Scheme (NFSS), which contains an error.^[33] The error is that the control sequence \Large, which has been redefined to request a 17pt font, contains a typo: \cs[fontsize]{fontsiz} should be \fontsize.^[34]

Example 3.1. The Document BADFONT.TEX

\documentstyle{article}
% The following definition changes the font that LaTeX
% uses for the 'Large' font.  I have introduced a typo
% into the definition, “\fontsiz” should be “\fontsize”.
% The  first time a \Large font is requested, an error will occur.
\renewcommand{\Large}{\fontsiz{17}{20pt}\selectfont}
\begin{document}

This text precedes the first section header.

% Note: LaTeX uses the \Large font in section
% headers...this will fail in a confusing way
% because the error is deep within the definition
% of \section where \Large is used...
\section{First Section}

This is the first and only sentence of the first section.

\end{document}

When TeX processes this file, using LaTeX with the New Font Selection Scheme, it produces these error messages:

This is TeX, Version 3.1415 (C version 6.1)
LaTeX Version 2.09 <25 March 1992> with NFSS2
(badfont.tex (/work/nutshell/texguide/styles/latex/article.sty
Standard Document Style ‘article’ <14 Jan 92>.
(/work/nutshell/texguide/styles/latex/art10.sty)) (badfont.aux)
(/usr/local/lib/tex/inputs/nfss2/T1cmr.fd)
! Undefined control sequence.
\Large ->\fontsiz{17}{20pt}\selectfont
<argument> \reset@font \Large
                              \bf
\@sect ...x \ifdim \@tempskipa >\z@ \begingroup #6
                                      \relax \@hangfrom {\hskip ...
l.21 \end{section}
\section{First Section}

?

These messages exemplify the kind of confusing error messages that TeX produces. Remember the following rule: Always look at the first and last line of the TeX error message when trying to figure out what went wrong and where it went wrong. In this case, the first line is:

! Undefined control sequence.

and the last line is:

l.21 \end{section}
\section{First Section}

The error is that the control sequence \cs[fontsize]{fontsiz} is not defined and TeX was processing line 21 of the file when it occurred.

Log Files

You don't have to remember or write down the error messages that TeX produces. When TeX processes a document, it produces a transcript of everything that occurs; you can refer to this transcript later if you need to recall what errors occurred when you processed your document. TeX stores this transcript in a file which has the same name as the document and the extension .log. For example, if you process main.tex, TeX produces a transcript in main.log.

Note

Log files go in the current directory. TeX always places the log file in the current directory, even if you specify a path when you format your document. For example, if you process lectures/main.tex, TeX produces a transcript in main.log, not in lectures/main.log as you might expect.

Interpreting TeX Error Messages

The first line of a TeX error message begins with an exclamation point followed by the text of the message. The lines that follow it show the context in which the error occurred.^[35] In the previous example, the error message indicates an Undefined control sequence. This means that TeX encountered a control sequence which was not previously defined.

The final line, which says l.21 \section{First Section}, occurs right above the question mark prompt. It identifies the line in your document that TeX was processing when it encountered the error. The error occurred when TeX was at line 21 of the file, and that line began with \section{First Section}.

Between the first and last lines, TeX prints a detailed description of how the error occurred. This is necessary because the error may have occurred inside the replacement text of a macro that you used. When TeX encounters a control sequence, like \section, it has to look up the definition to figure out how to typeset your document. The definition of a control sequence may contain other control sequences which also have to be interpreted. It is possible for TeX to be several levels deep, as it was in this case, when an error occurs. To give the person who wrote the definition of the control sequence an opportunity to figure out what went wrong, TeX prints out a trace back of what happened before the error. As you gain experience with a particular macro package, you'll find the intervening lines more meaningful.

Correcting an error depends entirely on the nature of the error. In this case, all you need to do is correct the typo.

As stated above, there are six general classes of errors you might encounter when you run TeX. The following sections briefly describe each class.

Naming a File TeX Cannot Find

Missing documents are discussed in the section called “the section called “User Files”,” earlier in this chapter.

If you request a format file that cannot be found, TeX issues the following warning message:

Sorry, I can't find that format; will try the default

TeX then attempts to typeset your document with Plain TeX.^[36] To correct this problem, run TeX with the correct format file name. If the format file isn't available, you will have to build it. Chapter 4, Chapter 4, describes how to build format files for several common macro packages.

Misspelling a Control Sequence Name

Misspelling a control sequence name is one of the most common errors. For example, you might type \ipnut{chap1} in your document instead of \input{chap1}. The solution is straightforward and usually easy to identify. In many cases, you can simply proceed after encountering this error. Although TeX may not typeset your document correctly, you can continue to look for other errors. The section called “the section called “Interpreting TeX Error Messages”,” later in this chapter, describes how to continue after an error.

In some cases, TeX may become badly confused by a misspelled control sequence name, in which case you should give up and fix the spelling error before trying to process your document further. This may happen if you misspell a LaTeX environment name (\begin{itemze} instead of \begin{itemize}, for example),^[37] which will make LaTeX misinterpret many of the control sequences which follow.

Sometimes TeX will complain that a control sequence is undefined when you know that the control sequence is spelled correctly. When this occurs, make sure that you are using the correct format file (see the section “the section called “The Command Line”” earlier in this chapter), loading the correct macro files, and using the correct style options.

Failure to Close an Environment

Failure to close an environment is another very common error. There are several distinct errors in this category:

• Failure to insert a closing brace (}) for each opening brace may cause a “TeX capacity exceeded” error when TeX processes your document. This happens because sometimes TeX tries to read everything between braces into memory. If the closing brace is absent, TeX may run out of memory.

  If the braces are supposed to enclose the argument to a macro, you may also get this error:

  ! Paragraph ended before macro was complete.

  In order to help detect errors of this type, TeX doesn't ordinarily allow the argument of a macro to consist of more than one paragraph, so the first blank line after the place where you failed to type the closing brace may produce this error.

• Failure to close a begin/end environment pair causes LaTeX to complain about a mismatch when it encounters the next \end{\texttt{environment}} command.
• If your document ends with an open environment, TeX will warn you that:

  ! (\end occurs inside a group at level n)

  where n is the number of open groups, usually 1.

• Failure to close a mathematics environment will result in the error:

  ! Missing $ inserted

  when TeX reaches a macro that does not make sense in mathematics mode (like \section) or when a surrounding group ends.

Math Outside of Math Mode

TeX has a lot of operators for special treatment of mathematical formulas. These operators must occur inside mathematics mode, which is usually delimited by dollar signs in your document.

If you attempt to use math operators, superscripts, subscripts, or other math-mode control sequences outside of mathematics mode, the following error will occur:

! Missing $ inserted

This is your clue that a mathematics environment has not been closed properly or that you failed to open one before using a math-mode operator.

For example, the underscore character is usually defined to be a math-mode operator which starts a subscript, in other words H${}_2$O produces “H${}_2$O” in your document.^[38] If you use the underscore outside of mathematics mode, such as in regular text:

The file “test_one” contains the ...

TeX will respond:

! Missing $ inserted
<inserted text>
                $
<to be read again>
                  _
The file “test_
                one” contains the ...
?

In LaTeX, the easiest way around this problem is to enclose the offending text in a “verbatim” macro, like this:

The file “test_one” contains the ...

Note that the argument to the macrois delimited by any two identical characters (in this case, two “+” signs).

In Plain TeX or another format, the problem can be circumvented in similar ways; consult the reference for the format you are using. Also consult Table 1.2 in Chapter 1, Chapter 1, for a list of special characters and how to type them in your documents.

Missing Fonts

The first time that you use each font, TeX loads font metric information about the font. The font metric information, stored in a TFM file, includes information about the sizes of each character as well as kerning and ligature information. These topics are discussed fully in Chapter 5, Chapter 5.

If you request a font that does not exist, for example crm10 (a misspelling of cmr10), TeX cannot find a TFM file for the font and therefore displays:

Font \myfont=crm10 not loadable: Metric (TFM) file not found

This means that TeX attempted to associate the font described by the TFM file crm10.tfm with the control sequence \myfont, but the TFM file didn't exist. You must have a TFM file for every font that you use.

A second kind of error---actually, a warning---occurs when you are using the New Font Selection Scheme (NFSS). The NFSS performs font substitution, if possible, when an unknown font is requested. The NFSS is described in Chapter 4, Chapter 4, in the “the section called “LaTeX”” section.

Everything Else

There are, unfortunately, lots of other errors that can occur. Some of the errors are directly related to TeX while others are warning and error messages associated with particular macro packages. There is no way to catalog every one of them or suggest what can be done in every case.

The best advice I can offer is to isolate the problem in as small a document as possible, consult the references you have available very carefully, and, if all else fails, forward your problem to one of the electronic forums that deal with TeX (the Info-TeX mailing list and the comp.text.tex newsgroup, for example).

The Question Mark Prompt

When TeX encounters an error, it displays an error message and a summary of the error, as described in the section called “the section called “What About Errors?”” earlier in this chapter. Following the error, TeX normally stops and displays the question mark prompt.

If you type a question mark of your own at the prompt, TeX displays the actions available to you:

? ?
Type <return> to proceed,
S to scroll future error messages,
R to run without stopping, Q to run quietly,
I to insert something, E to edit your file,
1 or ... or 9 to ignore the next 1 to 9 tokens
of input, H for help, X to quit.
?

You can type any of the following responses at the question mark prompt:

Type Return to proceed.

Simply typing Return will cause TeX to ignore the error and proceed. Depending on the nature of the error, this may cause more errors immediately or later on.

Type S to scroll future error messages.

Typing S tells TeX to continue and not to stop for most future errors. TeX will continue to print the error messages, both to the terminal and to the log file, but it will not display the question mark prompt again.

TeX will still stop and ask about missing files.

Type R to run without stopping.

The R option is just like S except that it tells TeX to ignore missing files as well. TeX will proceed blindly forward as best as it can. You will still see all of the error messages scroll by as TeX proceeds.

Type Q to run quietly.

This option is just like R except that error messages are not displayed on the screen. The messages are saved in the log file, however, even though they are not displayed.

Type I to insert something.

If you notice a simple typo, you can correct it with the I command. For example, suppose that TeX complains of an undefined control sequence: \cte{kn:art1}. You recognize that this should have been \cite{kn:art1}. You can insert the correct control sequence by responding i\cite to the question mark prompt. TeX will ignore the misspelled control sequence and insert the (correct) sequence \cite in its place.

Inserting words or commands at the question mark prompt does not change your input file. It simply instructs TeX to pretend that your file contained a different sequence of words and commands. You must change the input file with an editor, or the same error will occur the next time you format the document.

Type E to edit your file.

This option terminates TeX. If your system is configured appropriately, an editor will be loaded automatically, and the cursor will be placed at the offending line in your input file. This is not possible in all environments.

Type n, where n is a number between 1 and 9.

This option tells TeX to ignore some of the input. After skipping over the number of tokens you request, TeX returns to the question mark prompt so that you can delete more tokens.

What's a token? When TeX reads an input file, it breaks each line down into the smallest, indivisible chunks that have meaning. These are called tokens. For the most part, tokens are individual characters. The exceptions are control sequences, which are single tokens, and white spaces which are also single tokens. There are other exceptions (and more technical definitions of “token”), but that's the gist of it.

Type H for help.

Typing H displays a slightly more verbose description of the error that occurred and, usually, suggests the nature of the corrective action that you might take.

Type X to quit.

Typing X tells TeX to stop immediately and ends the TeX program. If there are any completed pages (pages processed before the error, in other words), they are written to the DVI file before TeX ends.

^[25] {The exception occurs in some unix versions of TeX where provisions are made for different architectures to share the same format files. The exact same version of TeX must be running on both architectures for this to work.}

^[26] {The exact name of the environment variable differs between implementations.}

^[27] You will notice that I've used backslashes to separate directory components in the path. Environment variables are handled by the system-dependent portions of TeX, so it's okay to use backslashes here. You can also use forward slashes, but I use backslashes because that is more typical of MS-DOS and OS/2 environments.

^[28] {MS-DOS and OS/2 implementations of TeX may use Ctrl-Z (possibly followed by a carriage return) instead of Ctrl-C or Ctrl-D.}

^[29] {On unix systems, the same effect is often achieved with symbolic links. Most unix implementations look for different standard format files based upon the name of the executable that starts them.}

^[30] {In the unlikely event that you have a TeX document stored in a file with a name beginning with an ampersand, use the following trick to process that file: instead of running tex &file, run tex \input &file (or even tex &format \input &file).

^[31] {For example, oak.oakland.edu in the directory /pub/msdos/4DOS.}

^[32] {Typing the break character (Ctrl-C or Ctrl-Break, for example) sometimes works as well, but some implementations of TeX don't respond to the break character at every prompt. On unix systems, use Ctrl-D. EmTeX responds to Ctrl-Z followed by Return.}

^[33] {The details of LaTeX and the NFSS are discussed in Chapter 4, Chapter 4. It is simply convenient to use a concrete example in this case. Do not be concerned if you do not use LaTeX or the NFSS.}

^[34] {In practice, redefining a control sequence like $\$Large in a document is a bad idea. I've done it here only to provide an example of an error that occurs inside another macro.}

^[35] {The number of lines of context shown in the error message is determined by the value of the built-in parameter $\$errorcontextlines.}

^[36] {It is possible to make other formats the default, but in practice I've never seen it done.}

^[37] Technically, LaTeX environment names are not a control sequence names, but they behave in very much the same way in LaTeX.

^[38] {The empty curly braces are necessary in this example because otherwise there wouldn't be anything in front of the subscript command for TeX to subscript below. Typically, another digit or symbol would come in front of the subscript command. In this case, I didn't want the “H” and “O” in the math environment because letters are printed in math-italics in math mode.}