Teach me to debug

Question

Ok, 35 years of programming has not prepared me to debug tex errors. It's painful. I can't create an MWE because the point is to be able to debug in place.

Everything was working well, I would compile to check, and if anything goes wrong, undo and then fix. Then all of a sudden, texworks reported an error on line 204. Line 204 had nothing to do with it. Then it crashed. When I restarted, now I can see that it is now showing line 203 of the aux file. Which looks like this:

ExploringEngineering4.8.aux: 203 Undefined Control Sequence
                                 l.203 \@writfle          
                                 {toc}{\contentsline {chapter}{\numberline {58}Lab: SD Card}{...

When I go to the line of source that caused this error:

\lab{SD Card}

An SD card is a 

This is not the first time \lab has been encountered, so if it were the definition of lab, it should have happened way before.

I need to learn how to debug these sorts of problems without deleting thousands of lines.

Answer 1

Common Errors includes this annotated image of an error message:

You have the -file-line-error option on so you've also got filename:linenum at the start of the message, which is more useful.

The line containing the error is staggered at the point where TeX has stopped to complain. As Heiko mentioned in the comments, that provides something you can grep for in your source files (including any packages or classes that you've loaded).

There are a number of reasons for an error occurring in the .aux file:

• The build process was interrupted, corrupting the file.
• The .aux file was accidentally modified while viewing it in an editor (unlikely, but could happen).
• A command has been written to the .aux file that doesn't get defined until after the .aux file is read in at the start of the document.
• A command that writes information to the .aux file has an error in the code that's being written to the file, but not executed at that point in the document.

Anything in the .aux file that includes {toc}{\contentsline is typically produced through \addcontentsline, which is defined as:

\addtocontents {#1}{\protect \contentsline {#2}{#3}{\thepage }}

and \addtocontents is defined as:

\protected@write\@auxout{%
   \let\label\@gobble
   \let\index\@gobble
   \let\glossary\@gobble}%
{\string\@writefile{#1}{#2}}

The fact that your error message is in the form

\@writfle          
         {toc}{\contentsline {chapter}

suggests that \lab isn't using \addcontentsline (or \addtocontents) but explicitly uses \protected@write\@auxout or something has badly messed the definition of \addtocontents or something has corrupted the .aux file after it's been created.

A quick test is to show the definition of \lab just before its problematic usage (remove the .aux file first):

\show\lab
\lab{SD Card}

This will act like an error message, but the transcript will show the definition of that command. (More info on \show.) Does it use \addcontentsline? If so, add \show\addtocontents to check if its usual definition has changed.

If previous instances of \lab have worked fine, then it's possible something has gone wrong between this instance and the last, so try building up or hacking down the bit between the previous \lab and this one.

Answer 2

In order to debug your LaTeX errors, you should be able to create a MWE if you do not see where the error comes from.

The best bet is to use a divide and conquer method. Cut in half the code and remove those part. As you stated, it is time consuming.

However, some tools exist in order to automatize this as the Delta-Debug algorithm. You have to adapt the script to your need and then you'll have less code as a result and so be able to debug easily.