9

TeX will encounter an error with the following code:

\documentclass{article}
\test
\begin{document}
\end{document}

It will give a message as:

! Undefined control sequence.
<recently read> \test 

l.2 \test

I know this error is simply due to the undefined \test, but what does the <recently read> mean?

And if move \test after \begin{document}, there is no such thing then:

! Undefined control sequence.
l.3 \test

Another example is

\documentclass{article}
\begin{document}
a_b
\end{document}

and the correspoding message becomes <inserted text> now:

! Missing $ inserted.
<inserted text>
                $
l.3 a_
      b

The third example is a \par in the argument:

\documentclass{article}
\begin{document}
\begin{aa

}
\end{document}

which gives <to be read again>:

Runaway argument?
{aa 
! Paragraph ended before \begin was complete.
<to be read again> 
                   \par 
l.4

So what does the <recently read>, <to be read again>, <inserted text>, etc. mean?

  • 2
    Read the TeXbook Chapter 27: Recovery from Errors. – Henri Menke Jul 20 '19 at 6:08
  • 3
    Mean that understandable messages is not one of the TeX's strengths :) – Fran Jul 20 '19 at 7:03
  • 4
    @Fran Actually, TeX's error messages are very informative and understandable, if you are aware of all its output conventions and pay attention to the presence or absence of every character (including spaces) in the output… basically, if you are Donald Knuth :-) – ShreevatsaR Jul 20 '19 at 18:15
  • @ShreevatsaR And Cypher saw a see blonde girl on Matrix's code, but even with a lot of imagination the movie viewers saw only some odd characters descending in the screen :) – Fran Jul 20 '19 at 22:13
13

It's just part of the context, similar to l.2 which indicates line 2.

At any given time, TeX may be reading either from a line in a file, from the terminal or one of the read streams, or from a token list it had constructed earlier (by reading from a file, for example) and saved.

When printing out an error, TeX prints \errorcontextlines pairs of lines of context, similar to a stack trace shown by present-day programming languages. For each of the pairs of lines of context printed, the first part (on the first line) shows what kind of thing is being printed (either a line from a file, or one of a few kinds of token lists), and the rest (partly on the first line and partly on the second line) shows the actual contents. So for example, just as:

l.3 a_
      b

means that on line 3, TeX had read up to a_ and had not yet read b (at the time of error), similarly

<recently read> \test 
 

(the lines must be read in pairs) means that in the <recently read> type of token list, TeX had read up to \test and had not yet read… well, nothing remained to be read. Similarly, the pair of lines

<to be read again> 
                   \par 

means that in the <to be read again> type of token list, TeX had read up to, well, nothing, and had not yet read \par. (Of course it had already read \par from the input line, which is why this token list was created in the first place.)


It only remains to say what these different kinds of token lists are. In the TeX program, see §311 which takes care of looping and printing all the pairs of lines; see §312 which says to print either the location of the line or the type of token list (before printing the actual contents of the line or token list); see §313 which prints the location of the line (either <*> or <insert> or <read *> or <read n> for some n, or l.n for some n), and finally §314 which prints the type of token list:

314, type of token list

Most of these are self-explanatory. Of the others, backed_up is when TeX realizes it has read more than it needed for whatever it was doing, and puts back the “extra” tokens on the input stack, to be read the next time it needs tokens. This is printed as either <to be read again> or <recently read> depending on whether there's anything left to read in it or not. And inserted is when TeX itself inserts, for error-recovery, some tokens that you didn't type; this is printed as <inserted text>.


For completeness, let's take a more detailed look at each of the examples in the question.

If you had typed

\documentclass{article}

\test

(with a blank line after \documentclass{article}) then you'd only get:

! Undefined control sequence.
l.3 \test

? 

where the first line is the error message, the next pair of lines is the context (where l.3 is the location, with \test having been read and nothing left to read), and ? is the prompt. But as you typed

\documentclass{article}
\test

you get

! Undefined control sequence.
<recently read> \test 

l.2 \test

? 

which has an extra pair of lines of context: at bottom is l.2 \test with nothing remaining (as before), but above that there's also a token list (created by backing-up) that contains \test in it (and this token list has been fully read too). Why? The answer is that you could have typed something like \documentclass{article}[2018/09/03] (see if you can find out where this is documented), so after reading \documentclass{article}, TeX (because of the definition of \documentclass etc) was still looking for a [ when it saw the \test, and backed up because what it saw wasn't [ — it put the \test back on the input stack to be read again, and got done with expanding whatever macros \documentclass{article} entailed. Then it read \test (from the token list this time), and showed you the error.

Next example:

\documentclass{article}
\begin{document}
a_b

This is straightforward: TeX reads a, then reads _, which should have been in math mode and cannot be processed in the current (horizontal) mode, so it puts _ back on the input stack to be read again. Then, out of a misplaced desire to help you, it inserts a $ (remember, it has not yet really read and processed _, so effectively this inserted $ is after a and before _), and asks you for confirmation before processing even that $:

! Missing $ inserted.
<inserted text> 
                $
<to be read again> 
                   _
l.3 a_
      b
? 

Here the first line ! Missing $ inserted. is the error message, the next pair of lines

<inserted text> 
                $

is the top of the input stack (this is a token list of type inserted, of which nothing has been read and $ remains to be read), after which the next pair of lines

<to be read again> 
                   _

shows that there's next a backed-up token list to be read, after which the next pair of lines

l.3 a_
      b

shows that from line 3 of the input file, only b remains to be read. Unfortunately LaTeX's default settings result in only the first pair and last pair of context lines to be shown, which can add to the confusion.

Finally, your last example:

\documentclass{article}
\begin{document}
\begin{aa

}
\end{document}

here after showing you the non-ended token-list argument {aa, TeX shows the error message and context:

! Paragraph ended before \begin was complete.
<to be read again> 
                   \par 
l.4 

? 

where again after the error message the first pair of lines shows that the blank line after aa, which is treated as a \par token, has been put back on the input stack to be read next, that it has not yet been read, and similarly that on line 4 nothing has been read and nothing remains.

So you see TeX's error messages are rather well-structured, except that to make sense of the structure you need very good eyesight and to have read the manual very closely even in places where it doesn't explain things clearly. :-)

| improve this answer | |
  • The statement <recently read> has a token on its line and <to be read again> lists its token in the next line is true. These structures remind us about the two line structure of line messages but not more. TeX stacks <to be read again> messages if necessary; see, for example, the plain TeX input ^\bye. – Udo Wermuth Jul 20 '19 at 21:04
  • Your explanation TeX had read up to, well, nothing, and had not yet read \par seems to be odd. \par was read but it has been backed-up. See my example, in which \bye was read, expanded, and its first token was read and must be read again. There is another level above the input in the input that shows how much of \bye was processed. And in this line \par is read. Next, the but above that there's also a backed-up token list with \test in it is misleading. Nothing has been backed-up, TeX has digested this token; it isn't processed anymore. Otherwise there would be a loop. – Udo Wermuth Jul 20 '19 at 21:06
  • @UdoWermuth Thanks for your comments; I think we both have the same understanding of what's going on, but I'll try to edit my answer to avoid the confusion you mentioned. I'm talking about the input stack that TeX maintains internally. (Let's adopt the convention that the stack grows bottom to top.) So “in the <to be read again> type of token list, TeX […] had not yet read \par” means that TeX had finished reading \par from the input line, as a result of which it put it onto a token list of type “inserted”, and in that token list it had not yet read \par. – ShreevatsaR Jul 20 '19 at 21:37
  • @UdoWermuth I've made minor edits to the answer to clarify what you pointed out was perhaps unclear; please see revision 4 in this answer's revisions. Specifically, I changed my “there's also a backed-up token list with \test in it” to “there's also a token list (created by backing-up) that contains \test in it (and this token list has been fully read too)”, to avoid any confusion with the non-technical meaning of “backed-up”. – ShreevatsaR Jul 20 '19 at 21:56

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.