diff options
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.html | 1894 |
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 3. 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 I. An Introduction to TeX" /> - <link rel="previous" href="ch02.html" - title="Chapter 2. Editing" /> - <link rel="next" href="ch04.html" - title="Chapter 4. Macro Packages" /> - </head> - - <body> - <div class="navheader"> - <table border="0" cellpadding="0" cellspacing="0" - width="100%" summary="Navigation table"> - <tr> - <td align="left"> <a title="Making TeX Work" - href="index.html"><img src="figures/nav-home.png" - alt="Home" border="0" /></a> <a - title="Chapter 2. Editing" - href="ch02.html"><img src="figures/nav-prev.png" - alt="Prev" border="0" /></a> <a - title="Part I. An Introduction to TeX" - href="pt01.html"><img src="figures/nav-up.png" alt="Up" - border="0" /></a> <a - title="Chapter 4. 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 3. 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 - “small” 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 “big” 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 - “TeX capacity exceeded” 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 “<a - href="ch03.html#sec.logfiles" title="Log Files">the section - called “Log Files”</a>,” 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>“System” 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 “<a - href="ch01.html#sec.tex.controlsequences" - title="Boxes and Glue">the section called “Boxes - and Glue”</a>” in Chapter <a - href="ch01.html" - title="Chapter 1. The Big Picture">Chapter 1</a>, - <span class="emphasis"><em><a href="ch01.html" - title="Chapter 1. The Big Picture">Chapter 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 - “big” iniTeX to make format files for a big - TeX and a “small” 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 <a - href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 4</a>, - <span class="emphasis"><em><a href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 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'. -<*> \input rpt-data - -Please type another input filename: -</pre> - - <p>The general form of TeX error messages is discussed in - the section called “<a href="ch03.html#sec.errors" - title="What About Errors?">the section called “What - About Errors?”</a>” 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 “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,<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. 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 <a href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 4</a>, - <span class="emphasis"><em><a href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 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 <<span -class="emphasis"><em>switches</em></span>> <&<span -class="emphasis"><em>format</em></span>> <|<span -class="emphasis"><em>document</em></span>> <<span -class="emphasis"><em>tex-commands</em></span>> -</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 “<a - href="ch03.html#run.sec.formatfiles" - title="What Do You Run?">the section called “What - Do You Run?”</a>,” 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 (&)<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 “<a - href="ch02.html#sec.texcomp" title="Running TeX">the - section called “Running TeX”</a>” in - Chapter <a href="ch02.html" - title="Chapter 2. Editing">Chapter 2</a>, - <span class="emphasis"><em><a href="ch02.html" - title="Chapter 2. Editing">Chapter 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 - “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<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 '&lplain' \\nonstopmode \\input doc1</b></span> -</pre> - </div> - - <p>instead of</p> - - <div class="informalexample"> -<pre class="screen"> -$ <span -class="bold"><b>tex &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 - “doc2” 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 “<a - href="ch03.html#run.sec.misinterpret" - title="Misinterpretation of the command line">the section - called “Misinterpretation of the command - line”</a>” 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 3.1. </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 “<a href="ch03.html#sec.qprompt" - title="Interpreting TeX Error Messages">the section - called “Interpreting TeX Error - Messages”</a>,” 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. -<*> \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. -<*> \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, - “@”). 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 <a - href="ch03.html#ex.badfonttex" - title="Example 3.1. The Document BADFONT.TEX">Example 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 3.1. 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, “\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} -</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 <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} - -? -</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 - “<a href="ch03.html#sec.userfiles" - title="User Files">the section called “User - Files”</a>,” 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 <a href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 4</a>, - <span class="emphasis"><em><a href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 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 “<a - href="ch03.html#sec.qprompt" - title="Interpreting TeX Error Messages">the section - called “Interpreting TeX Error - Messages”</a>,” 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 “<a href="ch03.html#sec.clineopts" - title="The Command Line">the section called “The - Command Line”</a>” 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 “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.</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 - “H${}_2$O” 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 “test_one” contains the ... -</pre> - - <p>TeX will respond:</p> -<pre class="screen"> -! Missing $ inserted -<inserted text> - $ -<to be read again> - _ -The file “test_ - one” contains the ... -? -</pre> - - <p>In LaTeX, the easiest way around this problem is to - enclose the offending text in a “verbatim” - macro, like this:</p> -<pre class="screen"> - The file “<tt>test_one</tt>” contains the ... -</pre> - - <p>Note that the argument to the <tt>macro</tt>is - delimited by any two identical characters (in this case, - two “<tt>+</tt>” 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 <a - href="ch01.html#tab.acttype" - title="Table 1.2. How to Typeset Special Characters"> - Table 1.2</a> in Chapter <a href="ch01.html" - title="Chapter 1. The Big Picture">Chapter 1</a>, - <span class="emphasis"><em><a href="ch01.html" - title="Chapter 1. The Big Picture">Chapter 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 <a href="ch05.html" - title="Chapter 5. Fonts">Chapter 5</a>, - <span class="emphasis"><em><a href="ch05.html" - title="Chapter 5. Fonts">Chapter 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 <a href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 4</a>, - <span class="emphasis"><em><a href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 4</a></em></span>, - in the “<a href="ch04.html#sec.latex" - title="LaTeX">the section called - “LaTeX”</a>” 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 “<a href="ch03.html#sec.errors" - title="What About Errors?">the section called “What - About Errors?”</a>” 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 <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. -? -</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 - “token”), 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 - &file</b>, run <b>tex \input &file</b> (or even - <b>tex &format \input &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 <a - href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 4</a>, - <span class="emphasis"><em><a href="ch04.html" - title="Chapter 4. Macro Packages">Chapter 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 “H” and - “O” 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 2. Editing" - href="ch02.html"><img src="figures/nav-prev.png" - alt="Prev" border="0" /></a> </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"> <a - title="Chapter 4. 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 2. Editing </td> - - <td width="20%" align="center"><a - title="Part I. An Introduction to TeX" - href="pt01.html"><img src="figures/nav-up.png" alt="Up" - border="0" /></a></td> - - <td width="40%" align="right"> -  Chapter 4. Macro Packages</td> - </tr> - </table> - </div> - </body> -</html> - |