2

I'm trying to understand the error messages when using latex without having to google them all. The following example produces 10 errors when using TexpadTeX (based on TeX Version 3.14159265 with e-TeX extensions) running in extended mode embedded in Texpad 760 (preloaded format=latex 2021.3.29):

\documentclass[11pt]{article}
\usepackage{amsmath}
\begin{document}
\begin{gather}
    1=1

\end{gather}
\end{document}

The problem with the code above (from a user perspective) is that there is a blank line within the gather environment, which isn't allowed. The generated error messages however are the following:

  1. ! Paragraph ended before \gather was complete. <to be read again> \par l.6
  2. ! Missing $ inserted. <inserted text> $ l.6
  3. ! Missing \endgroup inserted. <inserted text> \endgroup l.6
  4. ! Display math should end with $$. <to be read again> \par l.6
  5. ! Misplaced \cr. \math@cr@@@ ->\cr l.7 \end{gather}
  6. ! Misplaced \noalign. \math@cr@@ ... \iffalse }\fi \math@cr@@@ \noalign {\vskip #1\relax } l.7 \end{gather}
  7. ! Misplaced \noalign. \black@ #1->\noalign {\ifdim #1>\displaywidth \dimen@ \prevdepth \nointerlin... l.7 \end{gather}
  8. ! Extra }, or forgotten \endgroup. \endgather ->\math@cr \black@ \totwidth@ \egroup $$\ignorespacesafterend l.7 \end{gather}
  9. ! Missing $ inserted. <inserted text> $ l.7 \end{gather}
  10. ! Display math should end with $$. <to be read again> \endgroup l.7 \end{gather}

I don't quite understand how someone could deduce the action "remove the empty line inside the gather environment" from these error messages. Which of these error messages points me in that direction?

Thanks in advance!

DummyVariable
  • 23
  • 3
  • 5
    The first line nails it pretty well. – mickep Jun 15 '23 at 11:06
  • 2
    Don't use empty lines in the math environments of amsmath. Empty lines would (as usual) result in an end of paragraph (aka \par), which is not supported and therefore results in the first error message. This is the only real error in your code. All others are aftereffects. Note: If you need such an empty line for source structuring use an empty comment instead (by adding a % at the beginning of the empty line). – cabohah Jun 15 '23 at 11:34
  • 1
    To be fair, if the first error was "Paragraph ended (or blank line found) before ...", the error message would be much more understandable. – Teepeemm Jun 15 '23 at 13:29
  • 1
    The messages are TeX error messages. If you understand TeX then you understand these messages. But, unfortunately, many LaTeX users don't understand TeX because LaTeX manuals often don't include TeX principles. For example, that empty line is tokenized by token processor as \par control sequence. And that a scanner of macro parameters dislike \par control sequence unless the macro is declared as \long – wipet Jun 15 '23 at 14:09

2 Answers2

6

TeX offers the functionality to continue compilation after an error. This is implemented because errors can sometimes be local and can therefore allow the rest of the document to be typeset normally, even if there are issues in the output around the error.

In my opinion this is an unfortunate design decision, because 1. the output can be suboptimal and often plain wrong, 2. it teaches users that it is ok to ignore errors, and 3. it makes it difficult to pinpoint the actual error that needs fixing (as is the case in the current question about gather).

In the default setting LaTeX compilers such as pdfLaTeX do not continue and immediately stop processing when the first error is found. Most editors and online environments, including TeXPad, however do enable this functionality, leading to much confusion.

Long introduction, the main point is: always look at the first error only, and ignore everything that comes after, because all other error messages are irrelevant for the root cause of the problem. In this case the first error message is:

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

This error indicates that a paragraph has ended while it should not have ended. In TeX there are two ways of ending a paragraph: with the command \par, or with an empty line.

The error message tells you that an unexpected paragraph ending was found, so to fix that you need to remove that paragraph ending. There is no \par in the code but there is an empty line. Therefore you know that you need to remove the empty line.

Granted, this requires the knowledge that empty line means paragraph ending, and that the solution is to remove that paragraph ending. This is part of learning TeX as a language, which will take some time and experience. Error messages can be cryptic, but once you learn some of these details then you will find that the information needed to fix the error is (almost) always indeed presented in the error message.

wipet
  • 74,238
Marijn
  • 37,699
  • 1
    A slight modification of your first statement:
    TeX offers the functionality to interactively correct an error and continue compilation.
    Most LaTeX users don't choose interactive compilation, but it can be a boon to productivity.     – barbara beeton Jun 15 '23 at 16:00
  • @barbarabeeton that is a useful clarification indeed, it makes the design choice more sensible. However, I still find it undesired that you are allowed to ignore the error in interactive mode instead of fixing it. Also when you correct an error interactively then you need to correct it in the source as well otherwise on the next compilation the error occurs again. So for productivity I guess it would be easier to abort, fix the error in the source, and recompile (unless the document is very long and it was already compiling for several minutes). – Marijn Jun 15 '23 at 20:20
  • 1
    Well, an unmatched \begin(env} ... \end{enx} can't be recovered interactively. (At least, I haven't figured out how), so termination is the best "out". I quit with "x", so the log is preserved, and I can review that to see where I made interactive updates. Good habit to develop. (But I first learned TeX78, not LaTeX.) – barbara beeton Jun 15 '23 at 20:25
  • My talk scheduled for TUG'23 is on "things LaTeX newbies should know" and this is one of the problems covered. As for purely amsmath confusion, it looks like there is something in the latest "Lettre GUTenberg" on exactly that. I haven't looked at it yet, but have seen the issue TOC, posted to the GUTenberg and tex-eds lists. – barbara beeton Jun 15 '23 at 20:30
  • @barbarabeeton what I mean is that if the source contains for example \emp{some text} (without h) and I run interactively then I can enter x (abort), or I\emph (fix the error), or just press enter to ignore the error and produce output without emphasis. This third option should not be offered I think. – Marijn Jun 16 '23 at 08:02
  • Regarding the "replace" option, if bypassed, it may not be obvious what the command should be, so I gather what you are saying is that the job should simply stop if that happens. That would, of course, require a significant change to TeX itself. What should be done if the job is not in interactive mode? Halt or continue? – barbara beeton Jun 16 '23 at 14:49
  • @barbarabeeton of course I don't really know how the processing works internally but pressing enter without any other input could be changed to be equivalent to x, i.e., abort. So either you (try to) fix the error or the process halts completely. Or take it further and make -halt-on-error the default and only mode, as I don't see the use case for interactive compilation anyway. I use \show regularly but maybe that could be reimplemented using \typein or something similar. – Marijn Jun 16 '23 at 16:02
  • Some related sentiments are expressed in https://tex.stackexchange.com/questions/13323/how-to-disable-the-prompt-on-error/13330 and the comments under that question. – Marijn Jun 16 '23 at 16:02
3

As a general rule, only the first in a series of error messages related to the same place is to be taken in consideration. The following ones are caused by the attempt at error recovery, but in this case even removing the offending \par (if in interactive mode) wouldn't solve the issue: this is a common problem when arguments to “short” commands contain the disallowed \par.

A macro can be either \long (accepting \par in its arguments) or not. Since \par can't work inside an amsmath alignment, all the related macros are not \long. Feeding \par to a non \long macro will stop the lookup for the argument and failure in error recovery is expected.

In this case the error message tells the user that a \par (or a blank line) is where it shouldn't be. The error mentions \gather and it should be common knowledge that \begin{env} executes at some point the command \env. The error message should be quite clear now: at line 6, inside a gather environment, there is a blank line or a spurious \par token. Remove it and rerun LaTeX.

egreg
  • 1,121,712