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.

Yossi Farjoun
  • 13,274
  • 10
  • 74
  • 96

3 Answers3

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.

Joseph Wright
  • 259,911
  • 34
  • 706
  • 1,036
  • 4
    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. 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? – Yossi Farjoun Aug 07 '10 at 16:29
  • 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 07 '10 at 20:28
  • 3
    Sure:
    • "Step into" means that instead of stepping "over" the macro (that is performing the whole macro), you would only perform the first step of the macro (and presumably see the code that pertains to the macro itself, and be able to step that code.) Similarly "step out" would reverse that step and pop one macro level out.
    • "Stack". Can you have variables that are "private" to a macro? If so, stack makes sence: there iss a stack of macros that called each other and it can be of interest.
    • "graphically look", hovertext of a variable shows the value of that variable.
     – Yossi Farjoun Aug 07 '10 at 20:43
  • 4
    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 08 '10 at 08:14
  • 2
    Of course, the debugger would be using \show and \showthe behind the scenes.....but it could be nice to have an interface that hide the details from me...another pipe-dream :-) – Yossi Farjoun Aug 08 '10 at 15:54
  • 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 04 '10 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 05 '10 at 05:18
  • 1
    Are you offering to write it :-) Like many people, I can see the point here but lack the technical experience to do anything about it (let alone the time required). – Joseph Wright Oct 05 '10 at 05:43
  • 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 '10 at 16:54
  • @dmckee: did not realize that. @Joseph Wright: I think TeX is great, and I use it almost every day. I wish I could help out with the future of TeX more actively, but right now I can only dream. This is my dream: Imagine if instead of learning Tikz and programming in TeX you could rely on your knowledge of a standard widely-known scripting language like python (which is catching imho.) Then, you'd get all the language constructs for free, and you wouldn't even have to learn a new language. – Neil G Oct 19 '10 at 21:56
  • (Although, in fairness, with all the friendly experts on tex.stackexchange, most of my TeX pains are gone. The big advantage to embedded python would be that the barrier to writing TeX packages would be a lot lower, and you'd maybe see many more packages that would be better-maintained and that would work together better.) – Neil G Oct 19 '10 at 22:48
  • 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 '10 at 07:04
  • 2
    In general programming using long macros is considered bad programming practice. Unfortunately this is what Tex is doing under hood. This is what Bjarne Stroustrup said about macros: "Almost every macro demonstrates a flaw in the programming language, in the program, or in the programmer.... When you use macros, you should expect inferior service from tools such as debuggers, cross-reference tools, and profilers." After programming for 15 years in C++ I must say that this is true. The macros in C++ are usefull for conditional compilation or encapsulating simple arithmetic expression ... – truthseeker Apr 13 '15 at 08:25
  • 2
    @truthseeker You can use shorter or longer macros in programming TeX. Traditionally only a few have been used as TeX's capacity was limited and using lots of names was not possible in practical documents. Nowadays that's not the case, and in for example expl3 we encourage using lots of short, focussed macros. Of course it's still an expansion language, but there are things one can do differently. – Joseph Wright Apr 13 '15 at 08:27
  • 2
    ... but not for serious work. Instead inline methods should be used. The C++ environment advantage in comparison with Tex is that it enables the programmer to see preprocessor output. A few times this showed as indispensable for me. Unfortunately this is not a case with Tex which I see as serious disadvantage. Its very hard to remember all the interdependencies between various commands in memory to determine why compilation fails or why the command is not doing what it is supposed to do. – truthseeker Apr 13 '15 at 08:29
  • 1
    @truthseeker It's a completely different mindset: I find debugging Lua quite tricky as it works the opposite way to the one I am used to :-) (One for chat if you want to discuss it.) – Joseph Wright Apr 13 '15 at 08:35
  • 2
    There are good things in Tex and Latex but I think it should be reworked from the scratch for user to have better control of the output and all the inner workings. Most of the time writing my report I need for finding the correct command instead of focusing on the content. – truthseeker Apr 13 '15 at 08:40
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/

Dayakar
  • 39
c_z
  • 531
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.

user202729
  • 7,143
  • 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 '21 at 14:33