Debugging LaTeX Files

If I claim that writing HTML files is coding, I might raise the ire of real programmers. Maybe that's as it should be, because web browsers are very forgiving of technical errors in HTML code and they will do their best to render something in the browser. But writing LaTeX files is coding for sure. How do I know? Because if you miscode the file, it will either not run at all or it will render something other than you thought.

I write all my HTML files in a generic text editor, like NotePad. I could use NotePad to write all my LaTeX files, but I don't. Instead, I use the TeX editor that comes with TeXWorks. Writing a LaTeX file is coding, and therefore it's useful to use an editor that helps us code LaTeX. Such assistance includes highlighting reserved words such as '\begin{document}' and '\end{document}' (in green), and macros such as '\maketitle'(in blue). If the '\end{document}' statement is missing, the file won't compile to give you a pdflatex output. By the way, the editor window and the pdflatex windows are different and they can be placed side-by-side for convenience.

As in all programming languages I know of, you have special enviroments that have a beginning and an ending. You have to tell the complier what they are, as they come in pair. In some languages they are begin...end or {...}, or whatever.

The most important bit of advice I can give is that as you edit your working program, you save it often under a new name, which you can go back to if you can't find your error in the most recent version. I learn 40 years ago to do this and I have been it ever since.

Say you have a math paper that is 50 pages long. It was compiled great a moment ago but after you started to edit page 8, you got some error and now it won't compile anymore. The first thing I do, obviously enough, is to look closely at what I had just worked on for a typo or a mismatch of curly braces, as they delimit subenvironments, or the like. Sometimes the error can be readily found. If it's a subtle error in a really complex equation (and I sometimes have to typeset them), they can be difficult to find the error, especially if is within a multi-line equation. In such a case, I often insert an '\end{document}' after where I think the error is (and remove it later). I may also comment out one or two lines to see if I can at least identify the offending line. Once I find and repair the error, I remove the comment characters '%' and remove the extra '\end{document}'.

Sometimes, the complier gets confused about what you are doing. If it asks you if it can delete the current auxiliary file so it can make a new one, you probably should do so. When I suspect that the auxiliary file is hindering the recovery of a fix, I can do one of two things: 1) either resave the file under a new name (as this will force the compiler to make a new auxiliary file), or 2) go to the File column on the extreme upper left and pull down to the 'Remove Aux Files...' Either of these choices frequently saves the day.

If you're using alignment in a math environment, using an '&', then be sure you have enough of them and in their correct places.

Sometimes your errors are just syntactical. For instance, say you try this $A^\alpha^v$. My LaTeX compiler tells me that this is an error, giving me the error message '! Double superscript.' Then I have to decide what I actually wanted. Did I mean $A^{\alpha^v}$ or $A^{\alpha v}$? By the way, the snippits '$A^{\alpha v$' and '$A^{\alpha v}' are troublesome. The former one will probably give you an immediate error of a missing delimiter, the latter one will probably give an error when it reaches a return.