summaryrefslogtreecommitdiff
path: root/Master/texmf-doc/doc/english/make-tex-work/html/ch03.html
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-doc/doc/english/make-tex-work/html/ch03.html')
-rw-r--r--Master/texmf-doc/doc/english/make-tex-work/html/ch03.html1894
1 files changed, 0 insertions, 1894 deletions
diff --git a/Master/texmf-doc/doc/english/make-tex-work/html/ch03.html b/Master/texmf-doc/doc/english/make-tex-work/html/ch03.html
deleted file mode 100644
index 788caf7f753..00000000000
--- a/Master/texmf-doc/doc/english/make-tex-work/html/ch03.html
+++ /dev/null
@@ -1,1894 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta name="generator"
- content="HTML Tidy for Linux/x86 (vers 1st March 2002), see www.w3.org" />
- <meta http-equiv="Content-Type"
- content="text/html; charset=ISO-8859-1" />
-
- <title>Chapter&#160;3.&#160;Running TeX</title>
- <link rel="stylesheet" href="mtw.css" type="text/css" />
- <meta name="generator"
- content="DocBook XSL Stylesheets V1.53.0" />
- <link rel="home" href="index.html" title="Making TeX Work" />
- <link rel="up" href="pt01.html"
- title="Part&#160;I.&#160;An Introduction to TeX" />
- <link rel="previous" href="ch02.html"
- title="Chapter&#160;2.&#160;Editing" />
- <link rel="next" href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages" />
- </head>
-
- <body>
- <div class="navheader">
- <table border="0" cellpadding="0" cellspacing="0"
- width="100%" summary="Navigation table">
- <tr>
- <td align="left">&#160;<a title="Making TeX Work"
- href="index.html"><img src="figures/nav-home.png"
- alt="Home" border="0" /></a>&#160;<a
- title="Chapter&#160;2.&#160;Editing"
- href="ch02.html"><img src="figures/nav-prev.png"
- alt="Prev" border="0" /></a>&#160;<a
- title="Part&#160;I.&#160;An Introduction to TeX"
- href="pt01.html"><img src="figures/nav-up.png" alt="Up"
- border="0" /></a>&#160;<a
- title="Chapter&#160;4.&#160;Macro Packages"
- href="ch04.html"><img src="figures/nav-next.png"
- alt="Next" border="0" /></a></td>
-
- <td align="right"><i>Making TeX Work</i> Version 1.0.1
- <span class="alpha-version">(<a
- href="co01.html"><em>Alpha</em></a>)</span></td>
- </tr>
- </table>
- </div>
-
- <div class="chapter">
- <div class="titlepage">
- <div>
- <h2 class="title"><a id="chap.running"
- name="chap.running"></a>Chapter&#160;3.&#160;Running
- TeX</h2>
- </div>
-
- <div>
- <p class="releaseinfo">$Revision: 1.1 $</p>
- </div>
-
- <div>
- <p class="pubdate">$Date: 2002/08/23 14:31:13 $</p>
- </div>
- <hr class="component-separator" />
- </div>
-
- <p>The heart of processing a document with TeX is running<a
- id="id2862591" class="indexterm" name="id2862591"></a><a
- id="id2862603" class="indexterm" name="id2862603"></a> 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.</p>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h2 class="title" style="clear: both"><a
- id="run.sec.formatfiles"
- name="run.sec.formatfiles"></a>What Do You Run?</h2>
- </div>
- </div>
-
- <p>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 <tt>tex</tt> runs
- TeX. You should substitute the name of the executable
- program on your own system for <tt>tex</tt><a
- id="id2862504" class="indexterm" name="id2862504"></a> in
- the examples that follow.</p>
-
- <p>Most implementations of TeX have some hard-coded memory
- limits<a id="id2862517" class="indexterm"
- name="id2862517"></a>. 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
- &#8220;small&#8221; TeX<a id="id2862533" class="indexterm"
- name="id2862533"></a><a id="id2862543" class="indexterm"
- name="id2862543"></a> that generally runs faster but has
- less memory available to process your documents. The other
- version, a &#8220;big&#8221; TeX<a id="id2869219"
- class="indexterm" name="id2869219"></a><a id="id2869229"
- class="indexterm" name="id2869229"></a>, can process more
- complex documents but may run more slowly. If you get a
- &#8220;TeX capacity exceeded&#8221; error, and you have a
- big TeX available on your system, try processing your
- document with the big TeX.</p>
-
- <p>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 &#8220;<a
- href="ch03.html#sec.logfiles" title="Log Files">the section
- called &#8220;Log Files&#8221;</a>,&#8221; 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.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h2 class="title" style="clear: both"><a id="id2869278"
- name="id2869278"></a>What Files Does TeX Need?</h2>
- </div>
- </div>
-
- <p>Naturally, TeX needs your input file in order to process
- it. However, TeX must be able to find several other files<a
- id="id2869287" class="indexterm" name="id2869287"></a><a
- id="id2869299" class="indexterm" name="id2869299"></a> 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:</p>
-
- <div class="informaltable">
- <table border="1">
- <colgroup>
- <col />
- <col />
- </colgroup>
-
- <tbody>
- <tr>
- <td><tt>/usr/local/lib/tex/formats</tt></td>
-
- <td>Format files</td>
- </tr>
-
- <tr>
- <td><tt>/usr/local/lib/tex/pool</tt></td>
-
- <td>Pool files</td>
- </tr>
-
- <tr>
- <td><tt>/usr/local/lib/tex/formats</tt></td>
-
- <td>Format files</td>
- </tr>
-
- <tr>
- <td><tt>/usr/local/lib/tex/inputs</tt></td>
-
- <td>&#8220;System&#8221; input files</td>
- </tr>
-
- <tr>
- <td><tt>/usr/local/lib/tex/macros</tt></td>
-
- <td>(styles, macros, and miscellaneous</td>
- </tr>
-
- <tr>
- <td><tt>/usr/local/lib/tex/lib</tt></td>
-
- <td>files distributed with TeX)</td>
- </tr>
-
- <tr>
- <td><tt>/usr/local/lib/tex/ps</tt></td>
-
- <td>PostScript support files</td>
- </tr>
-
- <tr>
- <td><tt>/usr/local/lib/tex/fonts/pk</tt></td>
-
- <td><tt>PK</tt> fonts</td>
- </tr>
-
- <tr>
- <td><tt>/usr/local/lib/tex/fonts/vf</tt></td>
-
- <td>Virtual fonts</td>
- </tr>
-
- <tr>
- <td><tt>/usr/local/lib/tex/fonts/tfm</tt></td>
-
- <td><tt>TFM</tt> metrics</td>
- </tr>
- </tbody>
- </table>
- </div>
-
- <p>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, <tt>C:$\$TEX</tt> 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 <tt>fmt</tt> or
- <tt>fmts</tt>, rather than <tt>formats</tt>). Input files
- may occur in one or more of the standard places listed
- above (<tt>inputs</tt>, <tt>macros</tt>, and <tt>lib</tt>)
- as well as a number of other places (<tt>texinputs</tt> is
- another common name).</p>
-
- <p>The files under the TeX tree usually come from outside
- distributions, so you don't have to change them often. (You
- definitely <span class="emphasis"><em>shouldn't</em></span>
- put your personal macro files in that tree, even if you do
- have access to it.)</p>
-
- <p>The following sections describe, in more detail, each of
- the files that TeX needs.</p>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="id2869610"
- name="id2869610"></a>Pool Files</h3>
- </div>
- </div>
-
- <p>Pool files contain string constants used by TeX at
- runtime. Each time TeX is compiled, it creates a pool
- file<a id="id2869621" class="indexterm"
- name="id2869621"></a> unique to the version being
- compiled. The pool file from one version of TeX will not
- work with a different version.</p>
-
- <p>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.</p>
-
- <p>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.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="id2869651"
- name="id2869651"></a>Format Files</h3>
- </div>
- </div>
-
- <p>As mentioned in the section &#8220;<a
- href="ch01.html#sec.tex.controlsequences"
- title="Boxes and Glue">the section called &#8220;Boxes
- and Glue&#8221;</a>&#8221; in Chapter&#160;<a
- href="ch01.html"
- title="Chapter&#160;1.&#160;The Big Picture">Chapter&#160;1</a>,
- <span class="emphasis"><em><a href="ch01.html"
- title="Chapter&#160;1.&#160;The Big Picture">Chapter&#160;1</a></em></span>,
- 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<a id="id2869699"
- class="indexterm" name="id2869699"></a> 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.</p>
-
- <p><a id="run.sec.initexintro"
- name="run.sec.initexintro"></a>Format files are created
- by a special version of TeX, usually called iniTeX<a
- id="id2869724" class="indexterm" name="id2869724"></a>.
- 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<a id="id2869736" class="indexterm"
- name="id2869736"></a>. This is also why format files are
- not usually portable from one system to another,<sup>[<a
- id="id2869760" name="id2869760"
- href="#ftn.id2869760">25</a>]</sup> 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
- &#8220;big&#8221; iniTeX to make format files for a big
- TeX and a &#8220;small&#8221; iniTeX for a small TeX.</p>
-
- <p>You will find a complete discussion of macro packages
- and instructions for building format files for many of
- the common macro packages in Chapter&#160;<a
- href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a>,
- <span class="emphasis"><em><a href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a></em></span>.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="sec.userfiles"
- name="sec.userfiles"></a>User Files</h3>
- </div>
- </div>
-
- <p>When you run TeX<a id="id2869826" class="indexterm"
- name="id2869826"></a>, 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 <tt>myreport.tex</tt> in the
- directory <tt>/home/norm/tex/</tt> by running:</p>
-<pre class="screen">
-\$ <span class="bold"><b>tex /home/norm/tex/myreport</b></span>
-</pre>
-
- <p>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,
- <span class="emphasis"><em>always</em></span> use a
- forward slash when entering filenames for TeX.</p>
-
- <p>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 <tt>myreport.tex</tt> in
- order to process it:</p>
-<pre class="screen">
-\$ <span class="bold"><b>tex myreport</b></span>
-</pre>
-
- <p>If the file <tt>myreport.tex</tt> 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.</p>
-
- <p>The most common way to specify user-defined locations
- is by setting the <tt>TEXINPUTS</tt> environment
- variable<sup>[<a id="id2869931" name="id2869931"
- href="#ftn.id2869931">26</a>]</sup> to a list of
- subdirectories where TeX documents are kept. Setting
- <tt>TEXINPUTS</tt> specifies where TeX should look for
- <span class="emphasis"><em>documents</em></span> (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:</p>
-<pre class="screen">
-.:/usr/local/lib/tex/inputs:/home/norm/tex/inputs
-</pre>
-
- <p>On MS-DOS and OS/2 systems, it is a list of directory
- names separated by semicolons. A typical example looks
- like this:<sup>[<a id="id2869999" name="id2869999"
- href="#ftn.id2869999">27</a>]</sup></p>
-<pre class="screen">
-.;\tex\inputs;\tex\styles;\tex\macros
-</pre>
-
- <p>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
- <tt>\emtex\texinputs</tt> even if it does not occur in
- the <tt>TEXINPUTS</tt> path. In fact, there is no way to
- tell it <span class="emphasis"><em>not</em></span> to
- look there, short of renaming the directory (which is
- what I did).</p>
-
- <p>If TeX cannot find a file you specify, for example
- <tt>rpt-data.tex</tt>, it displays a prompt like this
- one:</p>
-<pre class="screen">
-! I can't find file `rpt-data.tex'.
-&lt;*&gt; \input rpt-data
-
-Please type another input filename:
-</pre>
-
- <p>The general form of TeX error messages is discussed in
- the section called &#8220;<a href="ch03.html#sec.errors"
- title="What About Errors?">the section called &#8220;What
- About Errors?&#8221;</a>&#8221; 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
- <tt>rpt-data.tex</tt> which it could not locate.</p>
-
- <p>Notice that TeX automatically added the extension
- <tt>.tex</tt><a id="id2870120" class="indexterm"
- name="id2870120"></a> to the name of the file it was
- looking for. In any context where you specify a filename,
- TeX will append <tt>.tex</tt> unless you specify an
- alternate extension.</p>
-
- <p>TeX responds to a &#8220;can't find file&#8221; 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,<sup>[<a id="id2870149"
- name="id2870149" href="#ftn.id2870149">28</a>]</sup> but
- other implementations insist that you enter a filename.
- In this case, you'll find it convenient to create an
- empty file called <tt>nul.tex</tt><a id="id2870165"
- class="indexterm" name="id2870165"></a> in a directory in
- your <tt>TEXINPUTS</tt> path so you can get around this
- requirement by supplying a dummy answer to the prompt.
- <tt>nul.tex</tt> is part of many standard
- distributions.</p>
- </div>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h2 class="title" style="clear: both"><a
- id="sec.clineopts" name="sec.clineopts"></a>The Command
- Line</h2>
- </div>
- </div>
-
- <p>Except for the name of a document, TeX has very few
- command-line options<a id="id2870206" class="indexterm"
- name="id2870206"></a>. 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.</p>
-
- <p>It is helpful to think of TeX, LaTeX, SliTeX,
- etc.&#160;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 <tt>tex.bat</tt>, <tt>latex.bat</tt>,
- and <tt>slitex.bat</tt>:</p>
-
- <div class="itemizedlist">
- <ul type="disc">
- <li>
- <p>The <tt>tex.bat</tt> file runs the TeX executable
- with the <tt>plain</tt> format file specified as an
- option.</p>
- </li>
-
- <li>
- <p>The <tt>latex.bat</tt> file runs TeX with the
- <tt>lplain</tt> format file.</p>
- </li>
-
- <li>
- <p>The <tt>slitex.bat</tt> file runs TeX with the
- <tt>splain</tt> format file.</p>
- </li>
- </ul>
- </div>
-
- <p>Now typing <span class="bold"><b>tex <span
- class="emphasis"><em>filename</em></span></b></span>
- processes Plain TeX documents; typing <span
- class="bold"><b>latex <span
- class="emphasis"><em>filename</em></span></b></span>
- processes LaTeX documents; and typing <span
- class="bold"><b>slitex <span
- class="emphasis"><em>filename</em></span></b></span>
- processes SliTeX documents.<sup>[<a id="id2870360"
- name="id2870360" href="#ftn.id2870360">29</a>]</sup> The
- role of format files and macro packages is described fully
- in Chapter&#160;<a href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a>,
- <span class="emphasis"><em><a href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a></em></span>.</p>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="sec.runtex.cmdcautions"
- name="sec.runtex.cmdcautions"></a>Command-line
- Options</h3>
- </div>
- </div>
-
- <p>A formal specification of the TeX command line<a
- id="id2870407" class="indexterm" name="id2870407"></a>
- looks like this:</p>
-
- <div class="informalexample">
-<pre class="screen">
-$ tex &lt;<span
-class="emphasis"><em>switches</em></span>&gt; &lt;&amp;<span
-class="emphasis"><em>format</em></span>&gt; &lt;|<span
-class="emphasis"><em>document</em></span>&gt; &lt;<span
-class="emphasis"><em>tex-commands</em></span>&gt;
-</pre>
- </div>
-
- <p>If this looks confusing, have no fear. I'll explain
- what it means in English.</p>
-
- <p>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 <span
- class="bold"><b>/I</b></span> as the switch to specify
- that iniTeX processing<a id="id2870468" class="indexterm"
- name="id2870468"></a> is desired (iniTeX, you may
- remember, was described in the section &#8220;<a
- href="ch03.html#run.sec.formatfiles"
- title="What Do You Run?">the section called &#8220;What
- Do You Run?&#8221;</a>,&#8221; 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.</p>
-
- <p>After any system-dependent switches, the first thing
- that you can put on the TeX command line is the name of
- the format file<a id="id2870509" class="indexterm"
- name="id2870509"></a> to use. If you specify this option,
- you must include it before any other options, and you
- must put an ampersand (&amp;)<a id="id2870520"
- class="indexterm" name="id2870520"></a> in front of the
- format file name. If you do not specify a format file,
- TeX will use a default format, usually Plain TeX.</p>
-
- <p>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<a id="id2870537"
- class="indexterm" name="id2870537"></a> contained in that
- file before looking at any other options that may
- follow.</p>
-
- <p>Finally, you can insert arbitrary TeX commands on the
- command line by typing them just as you would in a
- document. The section &#8220;<a
- href="ch02.html#sec.texcomp" title="Running TeX">the
- section called &#8220;Running TeX&#8221;</a>&#8221; in
- Chapter&#160;<a href="ch02.html"
- title="Chapter&#160;2.&#160;Editing">Chapter&#160;2</a>,
- <span class="emphasis"><em><a href="ch02.html"
- title="Chapter&#160;2.&#160;Editing">Chapter&#160;2</a></em></span>,
- describes one particular instance where this is very
- useful, but it isn't something that you are likely to do
- very often.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="id2870602"
- name="id2870602"></a>Command-line Cautions</h3>
- </div>
- </div>
-
- <p>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.</p>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h4 class="title"><a id="run.sec.misinterpret"
- name="run.sec.misinterpret"></a>Misinterpretation
- of the command line</h4>
- </div>
- </div>
-
- <p>Command lines that are typed at the operating system
- prompt are actually seen by your operating system's
- &#8220;command processor&#8221; 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<a id="id2870634"
- class="indexterm" name="id2870634"></a> is frequently
- interpreted as a <span class="emphasis"><em>shell
- escape</em></span> character<a id="id2870656"
- class="indexterm" name="id2870656"></a>, and the
- ampersand<a id="id2870668" class="indexterm"
- name="id2870668"></a> has another special meaning
- related to job control<a id="id2870677"
- class="indexterm" name="id2870677"></a>. 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.</p>
-
- <p>To insert these troublesome characters literally,
- you must enclose the relevant sections of the command
- line in quotation marks<a id="id2870695"
- class="indexterm" name="id2870695"></a> 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:</p>
-
- <div class="informalexample">
-<pre class="screen">
-$ <span
-class="bold"><b>tex '&amp;lplain' \\nonstopmode \\input doc1</b></span>
-</pre>
- </div>
-
- <p>instead of</p>
-
- <div class="informalexample">
-<pre class="screen">
-$ <span
-class="bold"><b>tex &amp;lplain \nonstopmode \input doc1</b></span>
-</pre>
- </div>
-
- <p>When using OS/2, place a ^ in front of an ampersand
- to prevent it from being interpreted as a command
- separator.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h4 class="title"><a id="sec.runtex.texwoopts"
- name="sec.runtex.texwoopts"></a>Filenames and
- TeX</h4>
- </div>
- </div>
-
- <p><a id="id2870772" class="indexterm"
- name="id2870772"></a><a id="id2870779"
- class="indexterm" name="id2870779"></a> <a
- id="id2870793" class="indexterm" name="id2870793"></a>
- 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.<sup>[<a
- id="id2870805" name="id2870805"
- href="#ftn.id2870805">30</a>]</sup> 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.</p>
-
- <p>On some systems, notably MS-DOS and OS/2, the
- backslash<a id="id2870848" class="indexterm"
- name="id2870848"></a> 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 <span
- class="emphasis"><em>must</em></span> use forward
- slashes to delimit filenames.</p>
-
- <p>For example, TeX will not process the file
- <tt>letter.tex</tt> in the <tt>\tex\docs</tt> directory
- of the current drive if you execute the following
- command line on an MS-DOS system:</p>
-
- <div class="informalexample">
-<pre class="screen">
-\$ <span class="bold"><b>tex \tex\docs\letter</b></span>
-</pre>
- </div>
-
- <p>Instead, you must type the following, regardless of
- the operating system you're using:</p>
-
- <div class="informalexample">
-<pre class="screen">
-\$ <span class="bold"><b>tex /tex/docs/letter</b></span>
-</pre>
- </div>
-
- <p>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.</p>
-
- <p>Unfortunately, filenames containing forward slashes
- are not always recognized by operating systems that use
- backslashes to delimit filenames. For example, under
- MS-DOS, <tt>IF EXIST C:/CONFIG.SYS</tt> returns
- false,<a id="id2870956" class="indexterm"
- name="id2870956"></a> even when a file called
- <tt>config.sys</tt> 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<a id="id2870971"
- class="indexterm" name="id2870971"></a>'s <b>4DOS</b>
- command processor. <b>4DOS</b><a id="id2871000"
- class="indexterm" name="id2871000"></a> 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 <b>4DOS</b> from many
- large MS-DOS archive sites on the Internet<sup>[<a
- id="id2871022" name="id2871022"
- href="#ftn.id2871022">31</a>]</sup> as well as most
- large bulletin board systems. The following lines,
- written in <b>4DOS</b><a id="id2871048"
- class="indexterm" name="id2871048"></a>'s extended
- batch language, will translate all backslashes in the
- environment variable <tt>TEXFN</tt> to forward
- slashes:</p>
-<pre class="screen">
-: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
-</pre>
-
- <p>These lines also work under OS/2 with JP Software's
- <b>4OS2</b> command processor (akin to <b>4DOS</b>;
- shareware versions of <b>4OS2</b> are also available).
- The same task can be completed in a single line with
- <b>REXX</b><a id="id2871106" class="indexterm"
- name="id2871106"></a> under OS/2:</p>
-<pre class="screen">
-TEXFN = TRANSLATE(TEXFN, '\', '/')
-</pre>
-
- <p><b>REXX</b> is an interpreted systems-programming
- language distributed with OS/2. <b>REXX</b> runs under
- many other IBM operating systems in addition to OS/2.
- Several versions of <b>REXX</b> are available for
- MS-DOS and unix systems, too.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h4 class="title"><a id="id2871151"
- name="id2871151"></a>Multiple documents</h4>
- </div>
- </div>
-
- <p>Keep in mind<a id="id2871161" class="indexterm"
- name="id2871161"></a> that TeX interprets only the
- first option after the format file name as a document
- name. If you type the command line:</p>
-
- <div class="informalexample">
-<pre class="screen">
-\$ <span class="bold"><b>tex doc1 doc2</b></span>
-</pre>
- </div>
-
- <p>TeX will process only <tt>doc1.tex</tt> as a
- document. The result of the above command line<a
- id="id2871206" class="indexterm" name="id2871206"></a>
- will be exactly as if you had typed the literal word
- &#8220;doc2&#8221; at the very end of the file
- <tt>doc1.tex</tt>.</p>
-
- <p>To get TeX to process both <tt>doc1</tt> and
- <tt>doc2</tt> as documents, type a command like the
- following:</p>
-
- <div class="informalexample">
-<pre class="screen">
-\$ <span class="bold"><b>tex doc1 \input doc2</b></span>
-</pre>
- </div>
-
- <p>or, for complete clarity,</p>
-
- <div class="informalexample">
-<pre class="screen">
-\$ <span class="bold"><b>tex \input doc1 \input doc2</b></span>
-</pre>
- </div>
-
- <p>In either case, the structure of your document files
- must allow them to be concatenated together. TeX does
- not process <tt>doc1</tt> and then process
- <tt>doc2</tt> separately. Instead, it processes all of
- <tt>doc1</tt> and appends the text in the file
- <tt>doc2</tt> directly onto the end of
- <tt>doc1</tt>.</p>
- </div>
- </div>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h2 class="title" style="clear: both"><a id="id2871334"
- name="id2871334"></a>TeX Without Options</h2>
- </div>
- </div>
-
- <p>If you run TeX without specifying any options<a
- id="id2871343" class="indexterm" name="id2871343"></a> at
- all, it prints out some introductory information, then
- produces a <tt>**</tt> prompt<a id="id2871366"
- class="indexterm" name="id2871366"></a> and stops. Here's
- what emTeX's <tt>tex386</tt> produces:</p>
-<pre class="screen">
-This is emTeX (tex386), Version 3.141 [3c-beta8]
-**
-</pre>
-
- <p>This is the only situation where the <tt>**</tt> prompt
- occurs. TeX now expects you to enter text. TeX will
- interpret anything you type after the <tt>**</tt> prompt
- <span class="emphasis"><em>exactly</em></span> as if you
- had typed it on the command line. All of the rules
- regarding slashes (described in &#8220;<a
- href="ch03.html#run.sec.misinterpret"
- title="Misinterpretation of the command line">the section
- called &#8220;Misinterpretation of the command
- line&#8221;</a>&#8221; earlier) apply to commands that you
- type at the <tt>**</tt> prompt. Remember, however, that
- input entered at the <tt>**</tt> prompt is not seen by the
- operating system, so don't use quotation marks or doubled
- backslashes.</p>
-
- <p>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 <tt>*</tt> prompt<a
- id="id2871494" class="indexterm" name="id2871494"></a>
- (single asterisk). Anything you type at the <tt>*</tt>
- 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 <tt>*</tt>
- prompt. You can, however, use \input to insert another
- file.</p>
-
- <p>If emTeX processes a document called
- <tt>unended.tex</tt>:</p>
-<pre class="screen">
-% 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...
-</pre>
-
- <p>the following output appears on the terminal:</p>
-<pre class="screen">
-This is emTeX (tex386), Version 3.141 [3c-beta8]
-**unended
-(unended.tex)
-*
-</pre>
-
- <p>You can exit from the TeX program at the <tt>*</tt>
- 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<a id="id2871573"
- class="indexterm" name="id2871573"></a><a id="id2871590"
- class="indexterm" name="id2871590"></a><a id="id2871603"
- class="indexterm" name="id2871603"></a><a id="id2871616"
- class="indexterm" name="id2871616"></a><a id="id2871626"
- class="indexterm" name="id2871626"></a>.</p>
-
- <div class="table">
- <a id="id2871639" name="id2871639"></a>
-
- <p class="title"><b>Table&#160;3.1.&#160;</b></p>
-
- <table summary="" border="1">
- <colgroup>
- <col align="left" />
- <col align="left" />
- </colgroup>
-
- <thead>
- <tr>
- <th align="left">Package</th>
-
- <th align="left">Command</th>
- </tr>
- </thead>
-
- <tbody>
- <tr>
- <td align="left">Plain TeX</td>
-
- <td align="left">\bye</td>
- </tr>
-
- <tr>
- <td align="left">LaTeX</td>
-
- <td align="left">\end{document}<a id="id2871705"
- class="indexterm" name="id2871705"></a></td>
- </tr>
-
- <tr>
- <td align="left">SliTeX</td>
-
- <td align="left">\end{document}</td>
- </tr>
-
- <tr>
- <td align="left">Lollipop</td>
-
- <td align="left">\Stop</td>
- </tr>
-
- <tr>
- <td align="left">TeXinfo</td>
-
- <td align="left"><tt>@bye</tt></td>
- </tr>
- </tbody>
- </table>
- </div>
-
- <p>If you do not know which format is in use, you can
- almost always get out with the following steps:<sup>[<a
- id="id2871781" name="id2871781"
- href="#ftn.id2871781">32</a>]</sup></p>
-
- <div class="orderedlist">
- <ol type="1">
- <li>
- <p>Type a control sequence that TeX will not
- recognize (control sequences \undefined and
- \gobbledygook will work). TeX will respond with the
- question mark prompt.</p>
- </li>
-
- <li>
- <p>Enter <span class="bold"><b>x</b></span> at the
- prompt. The question mark prompt is discussed fully
- in the section &#8220;<a href="ch03.html#sec.qprompt"
- title="Interpreting TeX Error Messages">the section
- called &#8220;Interpreting TeX Error
- Messages&#8221;</a>,&#8221; later in this
- chapter.</p>
- </li>
- </ol>
- </div>
-
- <p>To continue the above example, if I type \undefined at
- the <tt>*</tt> prompt, TeX will respond:</p>
-<pre class="screen">
-This is emTeX (tex386), Version 3.141 [3c-beta8]
-**unended
-(unended.tex)
-*<span class="bold"><b>\undefined</b></span>
-! Undefined control sequence.
-&lt;*&gt; \undefined
-
-?
-</pre>
-
- <p>If I enter <span class="bold"><b>x</b></span> at the
- question mark prompt, TeX will print several informative
- messages and then end, returning control to the operating
- system.</p>
-<pre class="screen">
-This is emTeX (tex386), Version 3.141 [3c-beta8]
-**unended
-(unended.tex)
-*\undefined
-! Undefined control sequence.
-&lt;*&gt; \undefined
-
-? <span class="bold"><b>x</b></span>
-No pages of output.
-Transcript written on unended.log.
-</pre>
-
- <p>One word of caution: some macro packages redefine the
- meaning of the backslash (\)<a id="id2871940"
- class="indexterm" name="id2871940"></a> character so that
- it doesn't function as the beginning of a control sequence
- (for example, the TeXinfo format uses the at-sign,
- &#8220;@&#8221;). In this case, you must precede the
- undefined control sequence by the escape character, even if
- it isn't the backslash.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h2 class="title" style="clear: both"><a
- id="sec.errors" name="sec.errors"></a>What About
- Errors?</h2>
- </div>
- </div>
-
- <p>When you write TeX documents, you will occasionally make
- mistakes<a id="id2871979" class="indexterm"
- name="id2871979"></a><a id="id2871992" class="indexterm"
- name="id2871992"></a><a id="id2872002" class="indexterm"
- name="id2872002"></a> 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:</p>
-
- <div class="orderedlist">
- <ol type="1">
- <li>
- <p>Naming documents or files that TeX cannot
- find.</p>
- </li>
-
- <li>
- <p>Misspelling the name of a TeX control
- sequence.</p>
- </li>
-
- <li>
- <p>Failing to close an environment or forgetting to
- insert a closing brace after an opening brace.</p>
- </li>
-
- <li>
- <p>Using math operators outside of math mode or
- forgetting to close an opened math environment.</p>
- </li>
-
- <li>
- <p>Requesting a font that TeX cannot find.</p>
- </li>
-
- <li>
- <p>Everything else.</p>
- </li>
- </ol>
- </div>
-
- <p>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.</p>
-
- <p>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&#160;<a
- href="ch03.html#ex.badfonttex"
- title="Example&#160;3.1.&#160;The Document BADFONT.TEX">Example&#160;3.1</a>
- shows a simple LaTeX document using the New Font Selection
- Scheme (NFSS), which contains an error.<sup>[<a
- id="id2872107" name="id2872107"
- href="#ftn.id2872107">33</a>]</sup> 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.<sup>[<a
- id="id2872135" name="id2872135"
- href="#ftn.id2872135">34</a>]</sup></p>
-
- <div class="example">
- <a id="ex.badfonttex" name="ex.badfonttex"></a>
-
- <p class="title"><b>Example&#160;3.1.&#160;The Document
- BADFONT.TEX</b></p>
-<pre class="screen">
-\documentstyle{article}
-% The following definition changes the font that LaTeX
-% uses for the 'Large' font. I have introduced a typo
-% into the definition, &#8220;\fontsiz&#8221; should be &#8220;\fontsize&#8221;.
-% 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}
-</pre>
- </div>
-
- <p>When TeX processes this file, using LaTeX with the New
- Font Selection Scheme, it produces these error
- messages:</p>
-<pre class="screen">
-This is TeX, Version 3.1415 (C version 6.1)
-LaTeX Version 2.09 &lt;25 March 1992&gt; with NFSS2
-(badfont.tex (/work/nutshell/texguide/styles/latex/article.sty
-Standard Document Style `article' &lt;14 Jan 92&gt;.
-(/work/nutshell/texguide/styles/latex/art10.sty)) (badfont.aux)
-(/usr/local/lib/tex/inputs/nfss2/T1cmr.fd)
-! Undefined control sequence.
-\Large -&gt;\fontsiz{17}{20pt}\selectfont
-&lt;argument&gt; \reset@font \Large
- \bf
-\@sect ...x \ifdim \@tempskipa &gt;\z@ \begingroup #6
- \relax \@hangfrom {\hskip ...
-l.21 \end{section}
-\section{First Section}
-
-?
-</pre>
-
- <p>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:</p>
-<pre class="screen">
-! Undefined control sequence.
-</pre>
-
- <p>and the last line is:</p>
-<pre class="screen">
-l.21 \end{section}
-\section{First Section}
-</pre>
-
- <p>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.</p>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="sec.logfiles"
- name="sec.logfiles"></a>Log Files</h3>
- </div>
- </div>
-
- <p>You don't have to remember or write down the error
- messages that TeX produces. When TeX processes a
- document, it produces a transcript<a id="id2872267"
- class="indexterm" name="id2872267"></a> 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 <tt>.log</tt>. For example, if you process
- <tt>main.tex</tt>, TeX produces a transcript in
- <tt>main.log</tt>.</p>
-
- <div class="note"
- style="margin-left: 0.5in; margin-right: 0.5in;">
- <h3 class="title">Note</h3>
-
- <p>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 <tt>lectures/main.tex</tt>, TeX
- produces a transcript in <tt>main.log</tt>, not in
- <tt>lectures/main.log</tt> as you might expect.</p>
- </div>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="sec.qprompt"
- name="sec.qprompt"></a>Interpreting TeX Error
- Messages</h3>
- </div>
- </div>
-
- <p>The first line of a TeX error message begins with an
- exclamation point followed by the text of the message<a
- id="id2872354" class="indexterm" name="id2872354"></a>.
- The lines that follow it show the context in which the
- error occurred.<sup>[<a id="id2872367" name="id2872367"
- href="#ftn.id2872367">35</a>]</sup> In the previous
- example, the error message indicates an <tt>Undefined
- control sequence</tt>. This means that TeX encountered a
- control sequence which was not previously defined.</p>
-
- <p>The final line, which says <tt>l.21 \section{First
- Section}</tt>, 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 <tt>\section{First Section}</tt>.</p>
-
- <p>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 <span class="emphasis"><em>trace
- back</em></span><a id="id2872434" class="indexterm"
- name="id2872434"></a> of what happened before the error.
- As you gain experience with a particular macro package,
- you'll find the intervening lines more meaningful.</p>
-
- <p>Correcting an error depends entirely on the nature of
- the error. In this case, all you need to do is correct
- the typo.</p>
-
- <p>As stated above, there are six general classes of
- errors you might encounter when you run TeX. The
- following sections briefly describe each class.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="id2872461"
- name="id2872461"></a>Naming a File TeX Cannot
- Find</h3>
- </div>
- </div>
-
- <p>Missing documents are discussed in the section called
- &#8220;<a href="ch03.html#sec.userfiles"
- title="User Files">the section called &#8220;User
- Files&#8221;</a>,&#8221; earlier in this chapter.</p>
-
- <p>If you request a format file<a id="id2872489"
- class="indexterm" name="id2872489"></a> that cannot be
- found, TeX issues the following warning message:</p>
-<pre class="screen">
-Sorry, I can't find that format; will try the default
-</pre>
-
- <p>TeX then attempts to typeset your document with Plain
- TeX.<sup>[<a id="id2872514" name="id2872514"
- href="#ftn.id2872514">36</a>]</sup> 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&#160;<a href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a>,
- <span class="emphasis"><em><a href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a></em></span>,
- describes how to build format files for several common
- macro packages.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="id2872549"
- name="id2872549"></a>Misspelling a Control Sequence
- Name</h3>
- </div>
- </div>
-
- <p>Misspelling a control sequence name<a id="id2872558"
- class="indexterm" name="id2872558"></a> 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 &#8220;<a
- href="ch03.html#sec.qprompt"
- title="Interpreting TeX Error Messages">the section
- called &#8220;Interpreting TeX Error
- Messages&#8221;</a>,&#8221; later in this chapter,
- describes how to continue after an error.</p>
-
- <p>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),<sup>[<a id="id2872615"
- name="id2872615" href="#ftn.id2872615">37</a>]</sup>
- which will make LaTeX misinterpret many of the control
- sequences which follow.</p>
-
- <p>Sometimes TeX will complain that a control sequence is
- undefined when you <span
- class="emphasis"><em>know</em></span> that the control
- sequence is spelled correctly. When this occurs, make
- sure that you are using the correct format file (see the
- section &#8220;<a href="ch03.html#sec.clineopts"
- title="The Command Line">the section called &#8220;The
- Command Line&#8221;</a>&#8221; earlier in this chapter),
- loading the correct macro files, and using the correct
- style options.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="id2872653"
- name="id2872653"></a>Failure to Close an
- Environment</h3>
- </div>
- </div>
-
- <p>Failure to close an environment<a id="id2872662"
- class="indexterm" name="id2872662"></a> is another very
- common error. There are several distinct errors in this
- category:</p>
-
- <div class="itemizedlist">
- <ul type="disc">
- <li>
- <p>Failure to insert a closing brace (<tt>}</tt>)
- for each opening brace may cause a &#8220;TeX
- capacity exceeded&#8221; 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.</p>
-
- <p>If the braces are supposed to enclose the
- argument to a macro, you may also get this error:<a
- id="id2872709" class="indexterm"
- name="id2872709"></a></p>
-<pre class="screen">
-! Paragraph ended before <span
-class="emphasis"><em>macro</em></span> was complete.
-</pre>
-
- <p>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.</p>
- </li>
-
- <li>
- <p>Failure to close a begin/end environment pair
- causes LaTeX to complain about a mismatch when it
- encounters the next
- \end{\texttt{<i><tt>environment</tt></i>}}
- command.<a id="id2872764" class="indexterm"
- name="id2872764"></a></p>
- </li>
-
- <li>
- <p>If your document ends with an open environment,
- TeX will warn you that:</p>
-<pre class="screen">
-! (\end occurs inside a group at level <span
-class="emphasis"><em>n</em></span>)
-</pre>
-
- <p>where <tt><i><tt>n</tt></i></tt> is the number
- of open groups, usually 1.</p>
- </li>
-
- <li>
- <p>Failure to close a mathematics environment will
- result in the error:</p>
-<pre class="screen">
-! Missing $ inserted
-</pre>
-
- <p>when TeX reaches a macro that does not make
- sense in mathematics mode (like \section) or when a
- surrounding group ends.</p>
- </li>
- </ul>
- </div>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="id2872844"
- name="id2872844"></a>Math Outside of Math Mode</h3>
- </div>
- </div>
-
- <p>TeX has a lot of operators for special treatment of
- mathematical formulas. These operators must occur inside
- <span class="emphasis"><em>mathematics mode</em></span><a
- id="id2872858" class="indexterm" name="id2872858"></a>,<a
- id="id2872867" class="indexterm" name="id2872867"></a>
- which is usually delimited by dollar signs in your
- document.<a id="id2872879" class="indexterm"
- name="id2872879"></a></p>
-
- <p>If you attempt to use math operators, superscripts,
- subscripts, or other math-mode control sequences outside
- of mathematics mode, the following error will occur:<a
- id="id2872899" class="indexterm"
- name="id2872899"></a></p>
-<pre class="screen">
-! Missing $ inserted
-</pre>
-
- <p>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.</p>
-
- <p>For example, the underscore character is usually
- defined to be a math-mode operator which starts a
- subscript, in other words <tt>H${}_2$O</tt> produces
- &#8220;H${}_2$O&#8221; in your document.<sup>[<a
- id="id2872944" name="id2872944"
- href="#ftn.id2872944">38</a>]</sup> If you use the
- underscore outside of mathematics mode, such as in
- regular text:</p>
-<pre class="screen">
-The file &#8220;test_one&#8221; contains the ...
-</pre>
-
- <p>TeX will respond:</p>
-<pre class="screen">
-! Missing $ inserted
-&lt;inserted text&gt;
- $
-&lt;to be read again&gt;
- _
-The file &#8220;test_
- one&#8221; contains the ...
-?
-</pre>
-
- <p>In LaTeX, the easiest way around this problem is to
- enclose the offending text in a &#8220;verbatim&#8221;
- macro, like this:</p>
-<pre class="screen">
- The file &#8220;<tt>test_one</tt>&#8221; contains the ...
-</pre>
-
- <p>Note that the argument to the <tt>macro</tt>is
- delimited by any two identical characters (in this case,
- two &#8220;<tt>+</tt>&#8221; signs).</p>
-
- <p>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&#160;<a
- href="ch01.html#tab.acttype"
- title="Table&#160;1.2.&#160;How to Typeset Special Characters">
- Table&#160;1.2</a> in Chapter&#160;<a href="ch01.html"
- title="Chapter&#160;1.&#160;The Big Picture">Chapter&#160;1</a>,
- <span class="emphasis"><em><a href="ch01.html"
- title="Chapter&#160;1.&#160;The Big Picture">Chapter&#160;1</a></em></span>,
- for a list of special characters and how to type them in
- your documents.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="id2873082"
- name="id2873082"></a>Missing Fonts</h3>
- </div>
- </div>
-
- <p>The first<a id="id2873090" class="indexterm"
- name="id2873090"></a> time that you use each font, TeX
- loads font metric information about the font. The font
- metric information, stored in a <tt>TFM</tt> file,
- includes information about the sizes of each character as
- well as kerning and ligature information. These topics
- are discussed fully in Chapter&#160;<a href="ch05.html"
- title="Chapter&#160;5.&#160;Fonts">Chapter&#160;5</a>,
- <span class="emphasis"><em><a href="ch05.html"
- title="Chapter&#160;5.&#160;Fonts">Chapter&#160;5</a></em></span>.</p>
-
- <p>If you request a font that does not exist, for example
- <tt>crm10</tt> (a misspelling of <tt>cmr10</tt>), TeX
- cannot find a <tt>TFM</tt> file for the font and
- therefore displays:</p>
-<pre class="screen">
-Font \myfont=crm10 not loadable: Metric (TFM) file not found
-</pre>
-
- <p>This means that TeX attempted to associate the font
- described by the <tt>TFM</tt> file <tt>crm10.tfm</tt>
- with the control sequence \myfont, but the <tt>TFM</tt>
- file didn't exist. You must have a <tt>TFM</tt> file for
- every font that you use.</p>
-
- <p>A second kind of error---actually, a warning---occurs
- when you are using the New Font Selection Scheme (NFSS)<a
- id="id2873221" class="indexterm" name="id2873221"></a>.
- The NFSS performs font substitution, if possible, when an
- unknown font is requested. The NFSS is described in
- Chapter&#160;<a href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a>,
- <span class="emphasis"><em><a href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a></em></span>,
- in the &#8220;<a href="ch04.html#sec.latex"
- title="LaTeX">the section called
- &#8220;LaTeX&#8221;</a>&#8221; section.</p>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h3 class="title"><a id="id2873273"
- name="id2873273"></a>Everything Else</h3>
- </div>
- </div>
-
- <p>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.</p>
-
- <p>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 <tt>Info-TeX</tt> mailing
- list<a id="id2873302" class="indexterm"
- name="id2873302"></a> and the <tt>comp.text.tex</tt>
- newsgroup<a id="id2873326" class="indexterm"
- name="id2873326"></a>, for example).</p>
- </div>
- </div>
-
- <div class="section">
- <div class="titlepage">
- <div>
- <h2 class="title" style="clear: both"><a id="id2873346"
- name="id2873346"></a>The Question Mark Prompt</h2>
- </div>
- </div>
- <a id="id2873352" class="indexterm" name="id2873352"></a>
-
- <p>When TeX encounters an error, it displays an error
- message and a summary of the error, as described in the
- section called &#8220;<a href="ch03.html#sec.errors"
- title="What About Errors?">the section called &#8220;What
- About Errors?&#8221;</a>&#8221; earlier in this chapter.
- Following the error, TeX normally stops and displays the
- question mark prompt.</p>
-
- <p>If you type a question mark of your own at the prompt,
- TeX displays the actions available to you:</p>
-<pre class="screen">
-? ?
-Type &lt;return&gt; 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.
-?
-</pre>
-
- <p>You can type any of the following responses at the
- question mark prompt:<a id="id2873401" class="indexterm"
- name="id2873401"></a></p>
-
- <div class="variablelist">
- <dl>
- <dt><span class="term">Type <b>Return</b> to
- proceed.</span></dt>
-
- <dd>
- <p>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.</p>
- </dd>
-
- <dt><span class="term">Type <b>S</b> to scroll future
- error messages.</span></dt>
-
- <dd>
- <p>Typing <b>S</b> 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.</p>
-
- <p>TeX will still stop and ask about missing
- files.</p>
- </dd>
-
- <dt><span class="term">Type <b>R</b> to run without
- stopping.</span></dt>
-
- <dd>
- <p>The <b>R</b> option is just like <b>S</b> 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.</p>
- </dd>
-
- <dt><span class="term">Type <b>Q</b> to run
- quietly.</span></dt>
-
- <dd>
- <p>This option is just like <b>R</b> 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.</p>
- </dd>
-
- <dt><span class="term">Type <b>I</b> to insert
- something.</span></dt>
-
- <dd>
- <p>If you notice a simple typo, you can correct it
- with the <b>I</b> 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 <tt>i\cite</tt> to the
- question mark prompt. TeX will ignore the misspelled
- control sequence and insert the (correct) sequence
- \cite in its place.</p>
-
- <p>Inserting words or commands at the question mark
- prompt <span class="emphasis"><em>does
- not</em></span> change your input file. It simply
- instructs TeX to <span
- class="emphasis"><em>pretend</em></span> 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.</p>
- </dd>
-
- <dt><span class="term">Type <b>E</b> to edit your
- file.</span></dt>
-
- <dd>
- <p>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.</p>
- </dd>
-
- <dt><span class="term">Type <b><i><tt>n</tt></i></b>,
- where <i><tt>n</tt></i> is a number between 1 and
- 9.</span></dt>
-
- <dd>
- <p>This option tells TeX to ignore some of the input.
- After skipping over the number of <span
- class="emphasis"><em>tokens</em></span> you request,
- TeX returns to the question mark prompt so that you
- can delete more tokens.</p>
-
- <p>What's a token<a id="id2873692" class="indexterm"
- name="id2873692"></a>? 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<a id="id2873705" class="indexterm"
- name="id2873705"></a>, which are single tokens, and
- white spaces which are also single tokens. There
- <span class="emphasis"><em>are</em></span> other
- exceptions (and more technical definitions of
- &#8220;token&#8221;), but that's the gist of it.</p>
- </dd>
-
- <dt><span class="term">Type <b>H</b> for
- help.</span></dt>
-
- <dd>
- <p>Typing <b>H</b> displays a slightly more verbose
- description of the error that occurred and, usually,
- suggests the nature of the corrective action that you
- might take.</p>
- </dd>
-
- <dt><span class="term">Type <b>X</b> to
- quit.</span></dt>
-
- <dd>
- <p>Typing <b>X</b> 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 <tt>DVI</tt> file
- before TeX ends.</p>
- </dd>
- </dl>
- </div>
- </div>
-
- <div class="footnotes">
- <br />
- <hr width="100" align="left" />
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2869760" name="ftn.id2869760"
- href="#id2869760">25</a>]</sup> {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.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2869931" name="ftn.id2869931"
- href="#id2869931">26</a>]</sup> {The exact name of the
- environment variable<a id="id2869936" class="indexterm"
- name="id2869936"></a><a id="id2869947" class="indexterm"
- name="id2869947"></a> differs between
- implementations.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2869999" name="ftn.id2869999"
- href="#id2869999">27</a>]</sup> You will notice that I've
- used backslashes<a id="id2870004" class="indexterm"
- name="id2870004"></a> 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.</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2870149" name="ftn.id2870149"
- href="#id2870149">28</a>]</sup> {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.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2870360" name="ftn.id2870360"
- href="#id2870360">29</a>]</sup> {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.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2870805" name="ftn.id2870805"
- href="#id2870805">30</a>]</sup> {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 <b>tex
- &amp;file</b>, run <b>tex \input &amp;file</b> (or even
- <b>tex &amp;format \input &amp;file</b>).</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2871022" name="ftn.id2871022"
- href="#id2871022">31</a>]</sup> {For example,
- <tt>oak.oakland.edu</tt> in the directory
- <tt>/pub/msdos/4DOS</tt>.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2871781" name="ftn.id2871781"
- href="#id2871781">32</a>]</sup> {Typing the break
- character (<b>Ctrl-C</b> or <b>Ctrl-Break</b>, 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
- <b>Ctrl-D</b>. EmTeX responds to <b>Ctrl-Z</b> followed
- by <b>Return</b>.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2872107" name="ftn.id2872107"
- href="#id2872107">33</a>]</sup> {The details of LaTeX and
- the NFSS are discussed in Chapter&#160;<a
- href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a>,
- <span class="emphasis"><em><a href="ch04.html"
- title="Chapter&#160;4.&#160;Macro Packages">Chapter&#160;4</a></em></span>.
- 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.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2872135" name="ftn.id2872135"
- href="#id2872135">34</a>]</sup> {In practice, redefining
- a control sequence like $\$<tt>Large</tt> 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.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2872367" name="ftn.id2872367"
- href="#id2872367">35</a>]</sup> {The number of lines of
- context shown in the error message is determined by the
- value of the built-in parameter
- $\$<tt>errorcontextlines</tt>.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2872514" name="ftn.id2872514"
- href="#id2872514">36</a>]</sup> {It is possible to make
- other formats the default, but in practice I've never
- seen it done.}</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2872615" name="ftn.id2872615"
- href="#id2872615">37</a>]</sup> Technically, LaTeX
- environment names are not a control sequence names, but
- they behave in very much the same way in LaTeX.</p>
- </div>
-
- <div class="footnote">
- <p><sup>[<a id="ftn.id2872944" name="ftn.id2872944"
- href="#id2872944">38</a>]</sup> {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 &#8220;H&#8221; and
- &#8220;O&#8221; in the math environment because letters
- are printed in math-italics in math mode.}</p>
- </div>
- </div>
- </div>
-
- <div class="navfooter">
- <table width="100%" summary="Navigation table">
- <tr>
- <td width="40%" align="left"><a
- title="Chapter&#160;2.&#160;Editing"
- href="ch02.html"><img src="figures/nav-prev.png"
- alt="Prev" border="0" /></a>&#160;</td>
-
- <td width="20%" align="center"><a title="Making TeX Work"
- href="index.html"><img src="figures/nav-home.png"
- alt="Home" border="0" /></a></td>
-
- <td width="40%" align="right">&#160;<a
- title="Chapter&#160;4.&#160;Macro Packages"
- href="ch04.html"><img src="figures/nav-next.png"
- alt="Next" border="0" /></a></td>
- </tr>
-
- <tr>
- <td width="40%" align="left">
- Chapter&#160;2.&#160;Editing&#160;</td>
-
- <td width="20%" align="center"><a
- title="Part&#160;I.&#160;An Introduction to TeX"
- href="pt01.html"><img src="figures/nav-up.png" alt="Up"
- border="0" /></a></td>
-
- <td width="40%" align="right">
- &#160;Chapter&#160;4.&#160;Macro Packages</td>
- </tr>
- </table>
- </div>
- </body>
-</html>
-