Mit TeX arbeiten

Der erste Lauf

Die einfachste Art TeX kennen zu lernen, ist damit zu arbeiten. Sie sollten daher beim Lesen dieses Kapitels die Möglichkeit haben, die Beispiele, die hier gezeigt werden, auszuprobieren. Dazu ist es hilfreich, wenn sie neben dem Programm TeX selber auch noch einen Editor und ein Programm zur Anzeige der Ergebnisse bei der Hand zu haben und zu wissen, wie sie bedient werden.

Wenn sie TeX starten, sollte dieses sich ungefähr so melden:

This is TeX, Version 3.14159 (Web2C 7.4.5)
**

Das doppelte Sternchen zeigt an, dass TeX auf eine Eingabedatei wartet. Geben sie an dieser Stelle '\relax' ein, zusammen mit dem Gegenschrägstrich und schließen sie die Eingabe mit einem Return ab, oder was immer bei ihrem System die Eingabe sonst abschließt. TeX war zwar bereit und in der Lage ganze Bücher zu setzen, aber durch die Angabe von '\relax' haben sie TeX gesagt, dass nun keine Eingabedatei kommt, sondern ein einfacher Lauf zu erwarten ist und dass es sich erst mal beruhigen soll.

Nach der Eingabe sollte sich TeX mit einem einfachen Sternchen zurück melden. Sie können nun mal 'Hallo' eingeben, oder was ihnen sonst so einfällt. Abschließend sollten sie dann '\end' eingeben. Daraufhin wird TeX irgendwas in der folgenden Art ausgeben:

[1]
Output written on texput.dvi (1 page, 212 bytes).
Transcript written on texput.log.

Die abschließende Mitteilung ist so zu lesen, dass TeX eine Seite ausgegeben hat, angezeigt durch die '[1]' und diese in die Datei 'texput.dvi' geschrieben hat. Wenn TeX keinen anderen Dateinamen kennt, dann wird die Ausgabe immer in die Datei 'texput' geschrieben. Die Endung '.dvi' steht für: device independent, was soviel wie geräteunabhängig bedeutet. Das ist das Ausgabeformat von TeX, das sich von den unterschiedlichsten Programmen auf die unterschiedlichsten Medien ausgeben lässt.

Sie sollten sich an dieser Stelle schlau machen, wie man eine solche Datei ausgeben kann und wie man sie auf dem Bidschirm sichtbar machen kann. Beides sollte durch verschiedene Programme geschehen.

Mit einer Datei

Nun kennen sie einen kompleten Lauf von TeX, angefangen mit der Eingabe in TeX, Erzeugung der Ausgabedatei und der Möglichkeit diese anzuzeigen und auszudrucken. Allerdings sollte nun ein Beispiel folgen, bei dem die Eingabe nicht einfach in TeX eingegeben wird, sondern in eine längere Datei, damit auch mehr Möglichkeiten vorgestellt werden können. Ich halte mich hier an das Originalbeispiel von D. Knuth.

Verwenden sie ihren Lieblingseditor (vim), um die folgenden Zeilen in eine Textdatei zu schreiben (ohne die Zahlen) und speichern sie diese unter dem Namen 'story.tex' ab.

1 \hrule
2 \vskip 1in
3 \centerline{\bf A SHORT STORY}
4 \vskip 6pt
5 \centerline{\sl by A. U. Thor}
6 \vskip .5cm
7 Once upon a time, in a distant
8 galaxy called \"O\"o\c c,
9 there lived a computer
10 named R.~J. Drofnats.
11
12 Mr.~Drofnats---or ``R. J.,'' as
13 he preferred to be called---
14 was happiest when he was at work
15 typesetting beautiful documents.
16 \vskip 1in
17 \hrule
18 \vfill\eject

Nun, der Inhalt dieser Datei mag vielleicht ein bißchen merkwürdig erscheinen, aber er soll dazu dienen mal ein paar weitere Eigenschaften von TeX kennen zu lernen.

In der ersten und in der 17ten Zeile steht der Befehl '\hrule'. Dieser sorgt dafür, dass ein horizontaler Strich über die Seite gezogen wird. In den Zeilen zwei und 16 findet sich der Befehl '\vskip'. Dieser fügt einen vertikalen Leerraum, also Abstand ein.

In den Zeilen von 7 bis 15 findet sich dann der eigentliche Text. Dieser besteht aus zwei Paragraphen. Der erste Paragraph wird durch die Leerzeile 15 beendet, der zweite durch den Befehl '\vskip' beendet, da es in Absätzen keinen vertikalen Leerraum gibt.

Es scheint so zu sein, dass der Text sehr viele Kontrollbefehle enthält. Das liegt aber eher daran, dass es sich um einen sehr untypischen Text handelt. Zum einen ist er sehr kurz und zum anderen ist er gedacht, um einige Befehle von TeX erklären zu können. Auffallend ist auf jeden Fall schon mal, dass man sich keine Gedanken mehr um Zeilenumbrüche oder Trennungen Gedanken machen muss. Das erledigt TeX.

In der achten Zeile findet sich die merkwürdige Kontruktion: '\"O\"o\c c'. Der Befehl '\"' ist ja schon bekannt und wird genutzt, um einen Umlaut zu erzeugen. Der Befehl '\c' dient dazu eine sogenannte Cedille zu erzeugen, das ist ein kleines Häkchen unter einem Buchstaben. Das Ergebnis dieser Anweisung ist daher:

Ööç

Der Name der weit entfernten Galaxy.

Der Rest besteht aus den Ligaturen für Anführungszeichen und Bindestriche, die schon bekannt sind. Nur die Tilde '~' ist noch nicht erklärt. Sie sorgt dafür, dass an dieser Stelle ein Leerzeichen eingefügt wird, an dem die Zeile nicht umbrochen werden kann. Somit ist z.B. gesichert, dass der Vor- und der Nachname in einer Zeile stehen.

Ab der 18ten Zeile stehen nun noch die schon bekannten Befehle, die den Rest der Seite auffüllen, '\vfill' und dann die Seite ausgeben '\eject'

Nun soll diese Datei übersetzt werden. Starten sie dazu TeX erneut, allerdings sollten sie nun, wenn TeX mit einem doppelten Sternchen zur Eingabe auffordert, den Namen der Daten 'story' an. Man kann auch den vollständigen Namen der Datei, also 'story.tex', abgeben, aber das ist nicht nötig. Wird keine Dateiendung angegeben, dann nimmt TeX autoamtisch an, dass die Endung '.tex' ist.

Noch ein kurzes Wort zu den Eingabeaufforderungen von TeX.

Wird TeX gestartet, dann fordert es zunächst mit einem doppelten Sternchen zur Eingabe auf und danach nur noch mit einem einzelnen Sternchen. Hier soll nun erst mal erklärt werden, worin denn der Unterschied genau liegt.

Wenn das doppelte Sternchen als Eingabeaufforderung gezeigt wird, dann stellt TeX jeder Eingabe, die nicht mit einem Backslash beginnt, ein '\input' voran. Man kann also auch '\input story' eingeben, aber das ist eigentlich nicht nötig, da dieser Befehl von TeX in dieser Situation automatisch gegeben wird. Wird ein Befehl eingegeben, der mit einem Gegenschrägstrich beginnt, dann wird der Befehl '\input' nicht vorangestellt. Daher hatte ich ihnen auch beim ersten Experiment geraten ein '\relax' einzugeben, was dazu führte, dass der 'interne' '\input'-Befehl nicht ausgeführt wurde,

Wenn bei dem doppelten Sternchen eine Eingabe gemacht wird, die mit einem Kaufmannsund ('&') beginnt, dann nimmt TeX an, dass es sich um eine Definitionsdatei handelt, die zunächst eingelesen werden muss, bevor die eigentliche TeX-Datei eingelesen wird. Normalerweise wird immer die Datei 'plain.tex' eingelesen, es wäre aber auch eine andere Datei denkbar.

TeX beginnt nun ihre Datei einzulesen. Dabei gibt es, ggf. nach diversen andern Meldungen, wie Versionsnummer u.ä. dann die Meldung '(story.tex ' aus. Anschließend wird ein '[1]' ausgegeben, um anzuzeigen, dass die erste Seite erfolgreich ausgegeben werden konnte. Nachdem dann ihre Datei vollständig eingelesen worden ist, wird dies durch die Ausgabe von ')' angezeigt.

TeX wird sich nun wieder mit dem bekannten einfachen Sternchen als Eingabeaufforderung melden, denn die Datei 'story.tex' beinhaltet keinen '\end' Befehl. Geben sie den Befehl '\end' per Hand ein. Sie finden dann eine Datei 'story.dvi', die sie sich genau wie die Ausgabe des ersten Beispiels ansehen können.

Fehler!

Mit dem letzten Beispiel wurde nun gezeigt, wie sie TeX dazu bringen die Eingabe aus einer Datei zu lesen. Der Rest dieses Kapitels soll nun dazu dienen, ihnen zu zeigen, wie TeX auf Fehler reagiert. Über kurz oder lang werden sie Fehler machen, das liegt in der Natur der menschlichen Sache. Es kommt aber darauf an, zu wissen, wie man dann weiter vorgehen sollte und das soll nun gezeigt werden.

Bevor es los geht, sollte allerdings noch etwas anderes erklärt werden. Ändern sie die 13te Zeile unserer Datei in:

he preferred to be called---% error has been fixed!

Das Prozentzeichen '% beendet eine Eingabezeile. Das Zeichen selber und alles, was hinter der Zeile steht, ignoriert TeX. Vor der nächsten Zeile wird auch kein Leerzeichen eingefügt, wie es sonst der Fall wäre. Mit diesem Zeichen können daher Kommentare in eine TeX-Datei geschrieben werden.

Experiment 3 will be to make \TeX\ work harder, by asking it to set the story in narrower and narrower columns. Here's how: After starting the program, type \begintt \hsize=4in \input story \endtt in response to the `|**|'. This means, ``Set the story in a 4-inch column.'' More precisely, ^|\hsize| is a primitive of \TeX\ that specifies the horizontal size, i.e., the width of each normal line in the output when a paragraph is being typeset; and ^|\input| is a primitive that causes \TeX\ to read the specified file. Thus, you are instructing the machine to change the normal setting of\/ |\hsize| that was defined by plain \TeX, and then to process |story.tex| under this modification. \TeX\ should respond by typing something like `|(story.tex [1])|' as before, followed by `|*|'. Now you should type \begintt \hsize=3in \input story \endtt and, after \TeX\ says `|(story.tex [2])|' asking for more, type three more lines \begintt \hsize=2.5in \input story \hsize=2in \input story \end \endtt to complete this four-page experiment. Don't be alarmed when \TeX\ screams `|Overfull| |\hbox|' several times as it works at the 2-inch size; that's what was supposed to go wrong during Experiment~3. There simply is no good way to break the given paragraphs into lines that are exactly two inches wide, without making the spaces between words come out too large or too small. Plain \TeX\ has been set up to ensure rather strict tolerances on all of the lines it produces: \begindisplay \hbox spread-1em{you don't get spaces between words narrower than this,\ and}\cr \hbox spread+1.679895em{you don't get spaces between words wider than this.}\cr \enddisplay If there's no way to meet these restrictions, you get an ^{overfull box}. And with the overfull box you also get (1)~a warning message, printed on your terminal, and (2)~a big black bar inserted at the right of the offending box, in your output. \ (Look at page~4 of the output from Experiment~3; the overfull boxes should stick out like sore thumbs. On the other hand, pages 1--3 should be perfect.) Of course you don't want overfull boxes in your output, so \TeX\ provides several ways to remove them; that will be the subject of our Experiment~4. But first let's look more closely at the results of Experiment~3, since \TeX\ reported some potentially valuable information when it was forced to make those boxes too full; you should learn how to read this data: \begintt Overfull \hbox (0.98807pt too wide) in paragraph at lines 7--11 \tenrm tant galaxy called []O^^?o^^Xc, there lived|| Overfull \hbox (0.4325pt too wide) in paragraph at lines 7--11 \tenrm a com-puter named R. J. Drof-nats. || Overfull \hbox (5.32132pt too wide) in paragraph at lines 12--16 \tenrm he pre-ferred to be called---was hap-|| \endtt Each overfull box is correlated with its location in your input file (e.g., the first two were generated when processing the paragraph on lines 7--11 of |story.tex|), and you also learn by how much the copy sticks out (e.g., 0.98807 points). Notice that \TeX\ also shows the contents of the overfull boxes in abbreviated form. For example, the last one has the words `he preferred to be called---was hap-', set in font |\tenrm| (10-point roman type); the first one has a somewhat curious rendering of `\"O\"o\c c', because the accents appear in strange places within that font. In general, when you see `^|[]|' in one of these messages, it stands either for the paragraph indentation or for some sort of complex construction; in this particular case it stands for an umlaut that has been raised up to cover an `O'. \dangerexercise Can you explain the `\|' that appears after `|lived|' in that message? \answer It represents the heavy bar that shows up in your output. \ (This bar wouldn't be present if\/ ^|\overfullrule| had been set to |0pt|, nor is it present in an underfull box.) \ddangerexercise Why is there a space before the `\|' in `|Drof-nats. |\|'\thinspace? \answer This is the ^|\parfillskip| space that ends the paragraph. In plain \TeX\ the parfillskip is zero when the last line of the paragraph is full; hence no space actually appears before the rule in the output of Experiment~3. But all hskips show up as spaces in an overfull box message, even if they're zero. You don't have to take out pencil and paper in order to write down the overfull box messages that you get before they disappear from view, since \TeX\ always writes a ``^{transcript}'' or ``^{log file}'' that records what happened during each session. For example, you should now have a file called |story.log| containing the transcript of Experiment~3, as well as a file called |texput.log| containing the transcript of Experiment~1. \ (The transcript of Experiment~2 was probably overwritten when you did number~3.) \ Take a look at |story.log| now; you will see that the overfull box messages are accompanied not only by the abbreviated box contents, but also by some strange-looking data about hboxes and glue and kerns and such things. This data gives a precise description of what's in that overfull box; \TeX\ wizards will find such listings important, if they are called upon to diagnose some mysterious error, and you too may want to understand \TeX's internal code some day. The abbreviated forms of overfull boxes show the hyphenations that \TeX\ tried before it resorted to overfilling. The ^{hyphenation} algorithm, which is described in Appendix~H\null, is excellent but not perfect; for example, you can see from the messages in |story.log| that \TeX\ finds the hyphen in `pre-ferred', and it can even hyphenate `Drof-nats'. Yet it discovers no hyphen in `galaxy', and every once in a~while an overfull box problem can be cured simply by giving \TeX\ a hint about how to hyphenate some word more completely. \ (We will see later that there are two ways to do this, either by inserting ^{discretionary hyphens} each time as in `\hbox{|gal\-axy|}', or by saying `\hbox{|\hyphenation{gal-axy}|}' once at the beginning of your manuscript.) In the present example, hyphenation is not a problem, since \TeX\ found and tried all the hyphens that could possibly have helped. The only way to get rid of the overfull boxes is to change the tolerance, i.e., to allow wider spaces between words. Indeed, the tolerance that plain \TeX\ uses for wide lines is completely inappropriate for 2-inch columns; such narrow columns simply can't be achieved without loosening the constraints, unless you rewrite the copy to fit. \TeX\ assigns a numerical value called ``^{badness}'' to each line that it sets, in order to assess the quality of the spacing. The exact rules for badness are different for different fonts, and they will be discussed in Chapter~14; but here is the way badness works for the roman font of plain \TeX: \begindisplay \hbadness10000 \hbox spread-.666667em{The badness of this line is 100.}& \quad(very tight)\cr \hbox spread-.333333em{The badness of this line is 12.}& \quad(somewhat tight)\cr \hbox{The badness of this line is 0.}& \quad(perfect)\cr \hbox spread.5em{The badness of this line is 12.}& \quad(somewhat loose)\cr %\hbox spread 1em{The badness of this line is 100.}& % \quad(loose)\cr % then "looser" \hbox spread 1.259921em{The badness of this line is 200.}& \quad(loose)\cr %\hbox spread 1.713em{The badness of this line is 500.}& % \quad(bad)\cr % then "worse" \hbox spread 2.155em{The badness of this line is 1000.}& \quad(bad)\cr \hbox spread 3.684em{The badness of this line is 5000.}& % actually 4995! \quad(awful)\cr \enddisplay Plain \TeX\ normally stipulates that no line's badness should exceed 200; but in our case, the task would be impossible since \begindisplay \hbadness 10000 `\hbox to 2in{tant galaxy called \"O\"o\c c, there}'\hskip 3em has badness 1521;\cr `\hbox to 2in{he preferred to be called---was}'\hskip 3em has badness 568.\cr \enddisplay So we turn now to Experiment~4, in which spacing variations that are more appropriate to narrow columns will be used. Run \TeX\ again, and begin this time by saying \begintt \hsize=2in \tolerance=1600 \input story \endtt so that lines with badness up to 1600 will be tolerated. Hurray! There are ^^|\tolerance| no overfull boxes this time. \ (But you do get a message about an {\sl underfull\/} box, since \TeX\ reports all boxes whose badness exceeds a certain threshold called ^|\hbadness|; plain \TeX\ sets |\hbadness=1000|.) \ ^^{underfull box} Now make \TeX\ work still harder by trying \begintt \hsize=1.5in \input story \endtt (thus leaving the tolerance at 1600 but making the ^{column width} still ^^{measure, see hsize} skimpier). Alas, overfull boxes return; so try typing \begintt \tolerance=10000 \input story \endtt in order to see what happens. \TeX\ treats 10000 as if it were ``infinite'' tolerance, allowing arbitrarily wide space; thus, a tolerance of 10000 will {\sl never\/} produce an overfull box, unless something strange occurs like an unhyphenatable word that is wider than the column itself. The underfull box that \TeX\ produces in the 1.5-inch case is really bad; with such narrow limits, an occasional wide space is unavoidable. But try \begintt \raggedright \input story \endtt for a change. \ ^^|\raggedright|(This tells \TeX\ not to worry about keeping the right margin straight, and to keep the spacing uniform within each line.) \ Finally, type \begintt \hsize=.75in \input story \endtt followed by `|\end|', to complete Experiment 4. This makes the columns almost impossibly narrow. \danger The output from this experiment will give you some feeling for the problem of ^{breaking a paragraph} into approximately equal lines. When the lines are relatively wide, \TeX\ will almost always find a good solution. But otherwise you will have to figure out some compromise, and several options are possible. Suppose you want to ensure that no lines have badness exceeding~500. Then you could set |\tolerance| to some high number, and |\hbadness=500|; \TeX\ would not produce overfull boxes, but it would warn you about the underfull ones. Or you could set |\tolerance=500|; then \TeX\ might produce overfull boxes. If you really want to take corrective action, the second alternative is better, because you can look at an overfull box to see how much sticks out; it becomes graphically clear what remedies are possible. On the other hand, if you don't have time to fix bad spacing---if you just want to know how bad it is---then the first alternative is better, although it may require more computer time. \dangerexercise When |\raggedright| has been specified, badness reflects the amount of space at the right margin, instead of the spacing between words. Devise an experiment by which you can easily determine what badness \TeX\ assigns to each line, when the |story| is set ragged-right in 1.5-inch columns. \answer Run \TeX\ with \hbox{|\hsize=1.5in|} \hbox{|\tolerance=10000|} \hbox{|\raggedright|} \hbox{|\hbadness=-1|} and then |\input story|. \TeX\ will report the badness of all lines (except the final lines of paragraphs, where fill glue makes the badness zero). \danger A parameter called ^|\hfuzz| allows you to ignore boxes that are only slightly overfull. For example, if you say |\hfuzz=1pt|, a box must stick out more than one point before it is considered erroneous. Plain \TeX\ sets |\hfuzz=0.1pt|. \ddangerexercise Inspection of the output from Experiment~4, especially page~3, shows that with narrow columns it would be better to allow white space to appear before and after a dash, whenever other spaces in the same line are being stretched. Define a ^|\dash| macro that does this. \answer |\def\extraspace{\nobreak \hskip 0pt plus .15em\relax}|\parbreak |\def\dash{\unskip\extraspace---\extraspace}|\par\nobreak\smallskip\noindent (If you try this with the story at 2-inch and 1.5-inch sizes, you will notice a substantial improvement. The |\unskip| allows people to leave a space before typing |\dash|. \TeX\ will try to hyphenate before |\dash|, but not before `|---|'; cf.\ Appendix~H\null. The ^|\relax| at the end of |\extraspace| is a precaution in case the next word is `|minus|'.) You were warned that this is a long chapter. But take heart: There's only one more experiment to do, and then you will know enough about \TeX\ to run it fearlessly by yourself forever after. The only thing you are still missing is some information about how to cope with ^{error messages}---i.e., not just with warnings about things like overfull boxes, but with cases where \TeX\ actually stops and asks you what to do next. Error messages can be terrifying when you aren't prepared for them; but they can be fun when you have the right attitude. Just remember that you really haven't hurt the computer's feelings, and that nobody will hold the errors against you. Then you'll find that running \TeX\ might actually be a creative experience instead of something to dread. The first step in Experiment 5 is to plant two intentional mistakes in the |story.tex| file. Change line~3 to \begintt \centerline{\bf A SHORT \ERROR STORY} \endtt and change `|\vskip|' to `|\vship|' on line~2. Now run \TeX\ again; but instead of `|story|' type `|sorry|'. The computer should respond by saying that it can't find file |sorry.tex|, and it will ask you to try again. Just hit \ this time; you'll see that you had better give the name of a real file. So type `|story|' and wait for \TeX\ to find one of the {\sl faux pas\/} in that file. Ah yes, the machine will soon stop,\footnote*{Some installations of \TeX\ do not allow interaction. In such cases all you can do is look at the error messages in your log file, where they will appear together with the ``help'' information.} after typing something like this: \begintt ! Undefined control sequence. l.2 \vship 1in ? \endtt \write16{\ifnum\pageno=\vshippage \else Redefine \string\vshippage to be \the\pageno\fi}% \TeX\ begins its error messages with `|!|', and it shows what it was reading at the time of the error by displaying two lines of context. The top line of the pair (in this case `|\vship|'\thinspace) shows what \TeX\ has looked at so far, and where it came from (`|l.2|', i.e., line number~2); the bottom line (in this case `|1in|'\thinspace) shows what \TeX\ has yet to read. The `^|?|'\ that appears after the context display means that \TeX\ wants advice about what to do next. If you've never seen an error message before, or if you've forgotten what sort of response is expected, you can type `|?|'\ now (go ahead and try it!); \TeX\ will respond as follows: \begintt Type 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. \endtt This is your menu of options. You may choose to continue in various ways: \smallskip\item{1.} Simply type \. \TeX\ will resume its processing, after attempting to recover from the error as best it can. \smallbreak\item{2.} Type `|S|'. \TeX\ will proceed without pausing for instructions if further errors arise. Subsequent error messages will flash by on your terminal, possibly faster than you can read them, and they will appear in your log file where you can scrutinize them at your leisure. Thus, `|S|' is sort of like typing \ to every message. \smallbreak\item{3.} Type `|R|'. This is like `|S|' but even stronger, since it tells \TeX\ not to stop for any reason, not even if a file name can't be found. \smallbreak\item{4.} Type `|Q|'. This is like `|R|' but even more so, since it tells \TeX\ not only to proceed without stopping but also to suppress all further output to your terminal. It is a fast, but somewhat reckless, way to proceed (intended for running \TeX\ with no operator in attendance). \smallbreak\item{5.} Type `|I|', followed by some text that you want to insert. \TeX\ will read this line of text before encountering what it would ordinarily see next. Lines inserted in this way are not assumed to end with a blank space. ^^{inserting text online} ^^{online interaction, see interaction} ^^{interacting with TeX} \smallbreak\item{6.} Type a small number (less than 100). \TeX\ will delete this many characters and control sequences from whatever it is about to read next, and it will pause again to give you another chance to look things over. ^^{deleting tokens} \smallbreak\item{7.} Type `|H|'. This is what you should do now and whenever you are faced with an error message that you haven't seen for a~while. \TeX\ has two messages built in for each perceived error: a formal one and an informal one. The formal message is printed first (e.g., `|! Undefined control sequence.|'\thinspace); the informal one is printed if you request more help by typing `|H|', and it also appears in your log file if you are scrolling error messages. The informal message tries to complement the formal one by explaining what \TeX\ thinks the trouble is, and often by suggesting a strategy for recouping your losses.^^{help messages} \smallbreak\item{8.} Type `|X|'. This stands for ``exit.'' It causes \TeX\ to stop working on your job, after putting the finishing touches on your |log| file and on any pages that have already been output to your |dvi| file. The current (incomplete) page will not be output. \smallbreak\item{9.} Type `|E|'. This is like `|X|', but it also prepares the computer to edit the file that \TeX\ is currently reading, at the current position, so that you can conveniently make a change before trying again. \smallbreak\noindent After you type `|H|' (or `|h|', which also works), you'll get a message that tries to explain that the control sequence just read by \TeX\ (i.e., |\vship|) has never been assigned a meaning, and that you should either insert the correct control sequence or you should go on as if the offending one had not appeared. In this case, therefore, your best bet is to type \begintt I\vskip \endtt (and \), with no space after the `|I|'; this effectively replaces |\vship| by |\vskip|. \ (Do it.) If you had simply typed \ instead of inserting anything, \TeX\ would have gone ahead and read `|1in|', which it would have regarded as part of a paragraph to be typeset. Alternatively, you could have typed `|3|'\thinspace; that would have deleted `|1in|' from \TeX's input. Or you could have typed `|X|' or `|E|' in order to correct the spelling error in your file. But it's usually best to try to detect as many errors as you can, each time you run \TeX, since that increases your productivity while decreasing your computer bills. Chapter~27 explains more about the art of steering \TeX\ through troubled text. \dangerexercise What would have happened if you had typed `|5|' after the |\vship| error? \answer \TeX\ would have deleted five tokens: |1|, |i|, |n|, \], |\centerline|. (The space was at the end of line~2, the |\centerline| at the beginning of line~3.) \danger You can control the level of interaction by giving commands in your file as well as online: The \TeX\ primitives ^|\scrollmode|, ^|\nonstopmode|, and ^|\batchmode| correspond respectively to typing `|S|', `|R|', or `|Q|' in response to an error message, and ^|\errorstopmode| puts you back into the normal level of interaction. \ (Such changes are global, whether or not they appear inside a group.) \ Furthermore, many installations have implemented a way to ^{interrupt} \TeX\ while it is running; such an interruption causes the program to revert to |\errorstopmode|, after which it pauses and waits for further instructions. What happens next in Experiment 5? \TeX\ will hiccup on the other bug that we planted in the file. This time, however, the error message is more elaborate, since the context appears on six lines instead of two: \begintt ! Undefined control sequence. \bf A SHORT \ERROR STORY \centerline #1->\line {\hss #1 \hss } l.3 \centerline{\bf A SHORT \ERROR STORY} |null ? \endtt You get multiline error messages like this when the error is detected while \TeX\ is processing some higher-level commands---in this case, while it is trying to carry out |\centerline|, which is not a primitive operation (it is defined in plain \TeX). At first, such error messages will appear to be complete nonsense to you, because much of what you see is low-level \TeX\ code that you never wrote. But you can overcome this hangup by getting a feeling for the way \TeX\ operates. First notice that the context information always appears in pairs of lines. As before, the top line shows what \TeX\ has just read (\thinspace `|\bf A SHORT \ERROR|'\thinspace), then comes what it is about to read (\thinspace`|STORY|'\thinspace). The next pair of lines shows the context of the first two; it indicates what \TeX\ was doing just before it began to read the others. In this case, we see that \TeX\ has just read `|#1|', which is a special code that tells the machine to ``read the first ^{argument} that is governed by the current control sequence''; i.e., ``now read the stuff that ^|\centerline| is supposed to center on a line.'' The definition in Appendix~B says that |\centerline|, when applied to some text, is supposed to be carried out by sticking that text in place of the `|#1|' in `|\line{\hss#1\hss}|'. So \TeX\ is in the midst of this expansion of\/ |\centerline|, as well as being in the midst of the text that is to be centered. \looseness-1 The bottom line shows how far \TeX\ has gotten until now in the |story| file. \ (Actually the bottom line is blank in this example; what appears to be the bottom line is really the first of two lines of context, and it indicates that \TeX\ has read everything including the `|}|' in line~3 of the file.) \ Thus, the context in this error message gives us a glimpse of how \TeX\ went about its business. First, it saw |\centerline| at the beginning of line~3. Then it looked at the definition of\/ |\centerline| and noticed that |\centerline| takes an ``argument,'' i.e., that |\centerline| applies to the next character or control sequence or group that follows. So \TeX\ read~on, and filed `|\bf A SHORT \ERROR STORY|' away as the argument to |\centerline|. Then it began to read the expansion, as defined in Appendix~B\null. When it reached the |#1|, it began to read the argument it had saved. And when it reached |\ERROR|, it complained about an undefined control sequence. \dangerexercise Why didn't \TeX\ complain about |\ERROR| being undefined when |\ERROR| was first encountered, i.e., before reading `|STORY}|' on line~3? \answer A control sequence like |\centerline| might well define a control sequence like |\ERROR| before telling \TeX\ to look at |#1|. Therefore \TeX\ doesn't interpret control sequences when it scans an argument. When you get a multiline error message like this, the best clues about the source of the trouble are usually on the bottom line (since that is what you typed) and on the top line (since that is what triggered the error message). Somewhere in there you can usually spot the problem. Where should you go from here? If you type `|H|' now, you'll just get the same help message about undefined control sequences that you saw before. If you respond by typing \, \TeX\ will go on and finish the run, producing output virtually identical to that in Experiment~2. In other words, the conventional responses won't teach you anything new. So type `|E|' now; this terminates the run and prepares the way for you to fix the erroneous file. \ (On some systems, \TeX\ will actually start up the standard text editor, and you'll be positioned at the right place to delete `|\ERROR|'. On other systems, \TeX\ will simply tell you to edit line~3 of file |story.tex|.) ^^{editing} When you edit |story.tex| again, you'll notice that line~2 still contains |\vship|; the fact that you told \TeX\ to insert |\vskip| doesn't mean that your file has changed in any way. In general, you should correct all errors in the input file that were spotted by \TeX\ during a run; the log file provides a handy way to remember what those errors were. \smallskip Well, this has indeed been a long chapter, so let's summarize what has been accomplished. By doing the five experiments you have learned at first hand (1)~how to get a job printed via \TeX; (2)~how to make a file that contains a complete \TeX\ manuscript; (3)~how to change the plain \TeX\ format to achieve columns with different widths; and (4)~how to avoid panic when \TeX\ issues stern~warnings. So you could now stop reading this book and go on to print a bunch of documents. It is better, however, to continue bearing with the author (after perhaps taking another rest), since you're just at the threshold of being able to do a lot more. And you ought to read Chapter~7 at least, because it warns you about certain symbols that you must not type unless you want \TeX\ to do something special. While reading the remaining chapters it will, of course, be best for you to continue making trial runs, using experiments of your own design. \ddanger If you use \TeX\ format packages designed by others, your error messages may involve many inscrutable two-line levels of macro context. By setting ^|\errorcontextlines||=0| at the beginning of your file, you can reduce the amount of information that is reported; \TeX\ will show only the top and bottom pairs of context lines together with up to |\errorcontextlines| additional two-line items. \ (If anything has thereby been omitted, you'll also see `|...|'.) \ Chances are good that you can spot the source of an error even when most of a large context has been suppressed; if not, you can say `|I\errorcontextlines=100\oops|' and try again. \ (That will usually give you an undefined control sequence error and plenty of context.) \ Plain \TeX\ sets |\errorcontextlines=5|.