5

     How do I debug BibTeX code? I would like to know how to:

  • step through execution,
  • step into and out of function calls,
  • set breakpoints,
  • visualize the stack,
  • watch the values of various variables,

et cetera. Are there any debugging options for BibTeX, perhaps like the unravel package (available on CTAN and on GitHub) for LaTeX?
     The reason I'm asking such a question is because I have been going through texdoc tamethebeast (Nicolas Markey's Tame the BeaST: The B to X of BibTeX) for a little while now and would like to have a better understanding of what's going on in some of the examples it presents in Chapter 4, particularly some of the later ones (starting around section 20 in said chapter) since they appear to get quite complex. There has to be a better way to go about inspecting how BibTeX code of the like executes and manipulates the stack than writing them out step by step in a sort of annotated textual control-flow graph in a raw text file or — I shudder to think! — getting out pencil and paper! (This last option would be less of a problem if I had room next to the computer from which I'm typing this on the desk it's standing on, but, still, it seems…needlessly archaic, shall I say…?)

Henri Menke
  • 109,596
RandomDSdevel
  • 297
  • I suppose one could also build things up piece by piece and then have BibTeX spit out whatever it's got so far (whether that be as an actual result or as a print statement or error on the command line,) but that way also leaves something to be desired, does it not? – RandomDSdevel Mar 20 '18 at 21:48
  • 1
    I guess that most people who know BibTeX are also reasonable TeX programmers, so the approach of 'Edit in $pop, check the values, track them on a piece of paper' is seen as pretty standard ... – Joseph Wright Mar 20 '18 at 21:52
  • Egads, that's regrettable! – RandomDSdevel Mar 20 '18 at 21:56
  • 4
    BibTeX is an independent program that's over 40% the size of TeX itself. Like TeX it is written in WEB, which is Pascal plus support for TeX documentation plus some preprocessor-like features that must have seemed a good idea at the time. Like TeX it is, in most distributions, converted to unreadable C code using web2c (instead of to unreadable Pascal code using tangle). So I guess the answer is: like TeX, BibTeX can be debugged (poorly) by building it from scratch and running in a debugger. Probably would be easier to just use Biber/BibLaTeX. – ShreevatsaR Mar 20 '18 at 22:33
  • Questions asking us to recommend or find a book, tool, software library, tutorial or other off-site resource are not really on-topic as they usually do not revolve around an abstract issue. Instead, describe the problem and what has been done so far to solve it or maybe ask on Software Recommendations SX. – Henri Menke Mar 20 '18 at 22:49
  • 1
    You could build your own binary of BibTeX with the debug, stats, and trace flags enabled, see https://github.com/texlive/texlive-source/blob/41c7068aea2af2c2684fe08c6d48722a94589e91/extra/bibtex/bibtex.web#L185-L213 – Henri Menke Mar 20 '18 at 22:53
  • @HenriMenke: I was sort of following the example precedent set by https://tex.stackexchange.com/questions/538/how-to-best-debug-latex and https://tex.stackexchange.com/questions/384871/why-doesnt-tex-have-a-proper-debugger, but that's fair enough. – RandomDSdevel Mar 20 '18 at 22:57
  • 1
    @HenriMenke I think the suggestion of building with trace turned on may be posted as an answer, because the question is really “how can I best debug BibTeX / see what's going on”, rather than asking for a software recommendation (when we all know that no such software exists). – ShreevatsaR Mar 20 '18 at 23:03
  • 1
    @ShreevatsaR Therefore the question would have to be rephrased because currently it literally asks “Is there a debugger for BibTeX?” and “Such a tool should allow [...]” rather than “How to debug BibTeX?”. – Henri Menke Mar 20 '18 at 23:07
  • @ShreevatsaR: Indeed, though this seems like an area where BibTeX could improve (perhaps BibLaTeX and/or Biber, as have been suggested, do better in this area, but the styles aren't interchangeable between systems.) By the way, are there any run-time configuration parameters of the same sort? It would be nice if I could use the copy of BibTeX I already have installed on my system in debug mode instead of having to build a new one, but I may do it if I absolutely have to. – RandomDSdevel Mar 20 '18 at 23:08
  • @HenriMenke: Yeah, I can reword it. Hold on just a bit… – RandomDSdevel Mar 20 '18 at 23:09
  • @HenriMenke: There you go. I tried to be minimally invasive the requisite edit, though, so it may not change enough…? – RandomDSdevel Mar 20 '18 at 23:16

1 Answers1

4

I think your best bet here is to compile your own bibtex executable where you enable the trace flag.

From the BibTeX source code (bibtex.web):

@^debugging@>
@^statistics@>
Some of the code below is intended to be used only when diagnosing the
strange behavior that sometimes occurs when \BibTeX\ is being
installed or when system wizards are fooling around with \BibTeX\
without quite knowing what they are doing. Such code will not normally
be compiled; it is delimited by the codewords
`$|debug|\ldots|gubed|$', with apologies to people who wish to
preserve the purity of English. Similarly, there is some conditional
code delimited by `$|stat|\ldots|tats|$' that is intended only for use
when statistics are to be kept about \BibTeX's memory/cpu usage,
and there is conditional code delimited by `$|trace|\ldots|ecart|$'
that is intended to be a trace facility for use mainly when debugging
\.{.bst} files.

@d debug == @{          { remove the |@{|' when debugging } @d gubed == @t@>@} { remove the|@}|' when debugging }
@f debug == begin
@f gubed == end
@#
@d stat == @{           { remove the |@{|' when keeping statistics } @d tats == @t@>@} { remove the|@}|' when keeping statistics }
@f stat == begin
@f tats == end
@#
@d trace == @{          { remove the |@{|' when in |trace| mode } @d ecart == @t@>@} { remove the|@}|' when in |trace| mode }
@f trace == begin
@f ecart == end
Henri Menke
  • 109,596