127

..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.

Improve this question
3

3 Answers 3

Reset to default
68

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.

Improve this answer
17
  • 10
    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, 2010 at 20:28
  • 7
    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, 2010 at 11:55
  • 25
    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, 2010 at 5:18
  • 10
    @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 --- ex-moderator kitten
    Oct 19, 2010 at 16:54
  • 8
    @Neil: I suspect you'll be pretty interested in LuaTeX :) It's the underlying engine that will support your "dream of the future" which doesn't seem so far-fetched these days.
    – Will Robertson
    Oct 20, 2010 at 7:04
53

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?

What about synctex? http://www.river-valley.zeeba.tv/direct-and-reverse-synchronization-with-synctex/

Improve this answer
2
  • 3
    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, 2011 at 18:37
  • 3
    By now there also exists the package lua-visual-debug for LuaTeX.
    – Henri Menke
    Oct 11, 2017 at 8:09
3

This answer only concern "serious debugging" (the actions that the OP mention in the question). For general tips on debugging compilation error, see compiling - How to trace LaTeX errors efficiently? - TeX - LaTeX Stack Exchange.

TeX already support some of these.

  • Breakpoint: Just add \MARK (or \error, or \ERROR, or whatever that causes an error in TeX) at the point that you want to break. When TeX is run in a console and in errorstopmode, it will break at the point for you to type commands in.

    This way you can't add breakpoint dynamically, however. At least you can redefine commands to add \MARK there.

  • Figuring out value of variables

    In the "TeX prompt", type ? to see what you can do there. In particular you can insert some TeX code to execute.

    So insert for example \show\var or \showthe\dimension etc.

    Note that if you don't cause another error (in this case \show makes TeX stop in errorstopmode) TeX will just continue running. (for example if you use \typeout or just redefine a macro/assign to a register)

    In the latter case, you may need a \relax to actually execute the command.

  • Step into/step over

    Not supported, unfortunately.

    For a limited subset of TeX there's the unravel package for now.

    There's also \pausing=1: the engine will pause on every line read. (this is not step-by-step)

    See also: errors - how to output each source line (number) during compilation (for debugging)? - TeX - LaTeX Stack Exchange

  • Examine the stack

    TeX doesn't really have a stack. The closest thing is \errorcontextlines.

These are not GUI, however. It's just that nobody have written one yet.

Improve this answer
1
  • I'm actually writing a GUI debugger to do the above, but because its usefulness is questionable it might take an indeterminate amount of time for me to post it.
    – user202729
    Dec 18, 2021 at 14:33

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .