[Tex/LaTex] How to trace LaTeX errors efficiently

compilingerrors

One of the most annoying things about LaTeX is that handling errors can be cumbersome and nerve-racking. In fact, it is the main reason that keeps me from actively recommending LaTeX to most people (not only Apple users). Handling LaTeX errors is not something for the average user.

The main reason for this, I believe, is that error messages tend to be cryptic and often outright misleading. The 'crypticness' problem can be solved by learning their basic structure. But the 'missleadingness' is a real problem.

For example, yesterday I struggled for more than an hour with a variety of error messages from biber such as this one:

Entity: line 2004: parser error : Extra content at the end of the document <bcf:citekey order="31">AuthorYear</bcf:citekey> ^

And from pdflatex, such as this one:

[9
! pdfTeX error (font expansion): auto expansion is only possible with scalable 
fonts.
\@EveryShipout@Output ...@Org@Shipout \box \@cclv 

l.987

But my question here does not concern these errors in particular. They are just illustrations for just how misleading these error descriptions can be. Because the problem that cause all this was simply that I had written 

\textsf{bla bla bla}

instead of 

\enquote{bla bla bla}

And I might add: that mistake was in line 918, so even the line numbers indicated in these error messages are rather far off (ok, biber is not referring to the .tex-file, but I had to learn that too).

I leave it to the geeks to figure out the logic that led to these error messages (cause I'm sure there is a (hidden) logic. But for those who wonder how on earth I could confuse \textsf with \enquote: the answer is: I did not type it, I used the (wrong) keyboard shortcut.

Now, call me stupid or whatever. This is just an example.

My point is: what strategies are there to systematically track down the source of errors when compiling a LaTeX document in an efficient way?

And let me add a more specific version of that question: Assuming that one strategy is to use some sort of version control system to go back to the last error free version of the file and identify the changes that cause the error, is there any automated or semi-automated way to do this. For example, I have my files on dropbox, which allows me to access previous versions of the file up to 30 days back. However, given that a new version is stored every time I hit "save", retrieving each version, saving it, and then loading it into my LaTeX editor to compile it seems rather unfeasible. Not to speak of the problem of relative paths when the old version is not saved in the same folder.

Best Answer

I'm not sure you want to read this ...

Only the first error LaTeX throws is important because the first error very often causes following errors which vanish after you corrected the first one.

So if you have to find errors

  • write only small parts of your code without compiling!
  • compile,
  • look only for the first error (usually located in the small part of new code),
  • find it (okay, that could be a hard job, but you will be better with more experience) and
  • correct it. Ignore the other errors. Now
  • compile again (and you will have usually not only one error less),
  • look only for the first error,
  • ...

I am used to compile each time I am thinking about my next paragraph to write. So I have only a few lines with new code and be able to locate errors faster.

If you have a lot of code to correct insert after some lines \end{document}, compile and check the errors. If everything is okay, move \end{document} some lines down, recompile and so on.

As @HaraldHanche-Olsen said in his comment:

"If you suspect your error can be anywhere inside a large-ish block of code, performing a binary search is often useful. With the \end{document} trick, instead of moving \end{document} by a few lines at a time, try putting it roughly halfway between the location which produces the error and one that doesn't.

I often comment out a block using \iffalse … \fi instead. Of course, with this technique, you must take care not to include part of an environment."

If you are using \input{...} or \include{...} in your document check with commenting it if it includes error(s). If so, you can use the macro \endinput to achieve a similar effect to \end{document} (see comment from @JuanA.Navarro).

If you need to use a version control for your TeX file please use a real system to use different versions like svn (subversion) ... Search this website for svn.

Related Question