# How to best debug LaTeX?

..and I don't mean finding out why it doesn't compile, I mean serious debugging: breakpoints, figuring out value of variables at a given moment during run/compile, stepping, examining a stack (is there one?), etc. All the things that we take for granted when debugging a "real" programming language. Since TeX is "turing-complete", I would like to be able to really see what is going on internally.

I'm guessing that a GUI interface for the debugger would be too much to ask, but if it exists, I'd love to hear about it.

-

The trace package will load everything that TeX is doing during a particular piece of the run. The problem with that is that you can get a lot of information very rapidly. Selectively using trace can give a lot of insight into problems. At a lower level, there are various tracing settings that TeX provides (and which the trace package makes use of). It's possible to set just some of these values to get TeX to log certain parts of what it is doing, for example just assignments. Normally, the trace package is enough.

For examining variables, the \wlog macro is the easiest way, although you can simply put\show or \showthe in the right places if it's a single thing you want to know.

One thing I do a lot (especially with infinite loops) is simply insert an undefined control sequence into the code (I use \MARK). This will stop TeX with an error, and I can therefore see where I'm up to. Not elegant, but it works for me.

The way TeX writes to the log can mean that you get an infinite loop without all of the data you want being added to the log. Strategic placement of \@@end (the TeX primitive \end renamed by LaTeX) can be used in these circumstances to force the run to end.

I'm not sure how a graphical debugger would work, but then I only really program in TeX, so I'm used to the approach I've outlined. I've never come across one.

-
Your comment probably makes perfect sense to you, as you obviously have lots of programming experience in other languages. However, as a programmer who works with TeX none of what you've said really makes sense! For example, what does 'step into' a macro mean? What 'stack'? How can you graphically 'look' at a variable (I guess you mean \showthe in some way)? Sorry if I'm being dense, but I at least need a more 'beginners' explanation. –  Joseph Wright Aug 7 '10 at 20:28
I'm not sue that TeX is really amenable to the approach you want. Remember that it's a macro expansion language, which reads from the input stream, tokenises and then expands/executes/prints material. So macros are expanded with the resulting 'replacement text' left in the input stream. At that stage the original presence of the macro is no longer relevant (or indeed available). Variables in TeX are not private to macros, but do have grouping. However, the only way to see what TeX is doing is to use TeX, and \show/\showthe. So I'm not sure what you want to do can be done. –  Joseph Wright Aug 8 '10 at 8:14
The real problem here is that TeX has no stack (apart from limited stack-like scoping for \begingroup...\endgroup), so you can't step into and out of macros. Macros are expanded in-line around tokenisation time, and then fed to TeX's stomach. The lexer can be dynamically reconfigured (catcodes). The fact that packages take advantage of TeX's tail-recursiveness means that 'how-did-I-get-here?' information is routinely scrubbed. This doesn't mean that a debugger is impossible (TeX is vaguely scheme-like here), but it would require starting almost from scratch (ie, not a gdb patch!) –  Norman Gray Oct 4 '10 at 11:55
Honestly, while I love TeX so much, the fact that it's a macro language rather than a fully-fledged Turing complete language with a scope, local variables, object-oriented objects, lambdas, etc. is a painful archaism. Programming languages have come a long way since TeX was designed, and it would be nice to one day (20 years from now?) keep the good parts of TeX and ditch the unfortunate limitations. –  Neil G Oct 5 '10 at 5:18
@Neil: TeX is Turing complete. A debugger for it should be possible, but it would work as an instrumented version of the TeX program. You would hook into the token recognition code and the macro expansion code (and presumably a few other places like character class redefinition) which would give it a slightly different character than using, say, gdb on C. –  dmckee Oct 19 '10 at 16:54

A graphical debugger would work as for other languages, you would be able to set breakpoints (positional or conditional), step over and into commands (commands being everything in the source including letters of course), view the stack (if such a thing exists in TeX..) examine variables, etc.

IMO it would make sense, and you are not the first to think about it. Unfortunately, it seems that previous projects to bring a such tool to TeX have been discontinued:

• Lutz Birkhahn. Tdb: An X11 TEX Debugger. Proceedings of the Eight European TEX Conference, September 26-30, 1994, Gdansk, Poland, pp 91-95.

A small report can be found here, p27:

Lutz Birkhahn discussed his work on developing debugging tools for TEX and presented Tdb, an extension to TEX that provides an interface to the Tk/Tcl X11 toolkit. This allowed him to set up a graphical user interface to allow one to set breakpoints, have stepwise execution, and to look at macro definitions and the value of variables.

However, it seems that ConTeXt does have a kind of visual debugging commands:

You can check ConTeXt's \showmakeup command from ConTeXt documentation:

We can visualize boxes by using \ruledhbox, \ruledvbox and \ruledvtop instead of \hbox, \vbox and \vtop. With \showmakeup we can visualise everything automatically and we can get some insight on the features of ConTEXt and TEX.

also featured in ConTeXt wiki: http://wiki.contextgarden.net/Visual_Debugging

At every point on the way you should be able to view the output, and this might be the most difficult part: can one view the partial dvi or pdf that is generated?

-
Great answer on the current facilities available. –  Will Robertson Oct 4 '10 at 1:30
Just a note - something like the Visual_Debugging in Latex, I guess, would be package (or option to geometry) showframe; but I wish I knew if there was something that can frame/box each and every letter as it is typeset... –  sdaau Aug 28 '11 at 18:37