Kdtyjb

I'm sure if you're reading this question you are already familiar with my love for pgfkeys. However, it is absolutely impossible to debug: tracingmacros is a total mess, with every key expanding to dozens of complex internal macros. I would like to be able to debug it the same way I can debug a program built by hand using def: watch the keys absorb their arguments, expand their values or execute their code, and proceed to the next key. I don't care how pgfk@try or whatever is defined, only that it looks for a key and does or doesn't find it, acting accordingly.

Currently, I debug by intimidation: tracingmacros=1 and lots of scrolling plus a bit of pattern recognition for the repetitive macro noise. It's too much to hope that there is some way of coercing pgfkeys into producing nicer output; it would require the author to have hand-coded a selectively populated call stack. I'm wondering, though, if anyone else familiar with this package could tell me how they figure out what's going on with their keys.

Related: How to best debug LaTeX? (by Yossi Farjoun; not coincidentally, this question is also really his, from a recent chat conversation.)

I have written a draft of a package that traces pgfkeys. I have tested it as much as I can stand, and it seems both to work and to be useful, but I am reluctant to publish it on CTAN before giving it a beta run. Therefore I am making it available only on my own website (no longer available) for now. It consists (for now) just of a .sty file with a comment block at the top describing how it works.

I would really appreciate any comments you might have, so I'm going to open up a second answer (CW) for feature requests and bug reports. Perhaps it's selfish, but I want reputation from this answer.

I will reply to items below in the chatroom trace-pgfkeys.

Feature requests

• (added by Andrew Stacey) I'd like to sometimes see the values that are being passed around. As a first case, when a key uses /.store in I'd like to know what was being stored in what.




• (Andrew Stacey again) I'd like to be able to follow particular keys, or families of keys. Looking at the output from this package, there's an awful lot going on! Often, I'm just interested in tracing how one piece works.

Bugs

• Processing an unknown key with a defined unknown handler (in the unknown key's path) in the verbose mode yields an error.

Here's a M(N)WE:

documentclass{article}



usepackage{pgfkeys}

usepackage[silent]{trace-pgfkeys}



begin{document}



pgfkeys{/bla/.unknown/.code=blabla}

pgfkeystracelevel{verbose}

pgfkeys{/bla/nonexisting}



end{document}

I investigated a bit and found the source of the error. In the second patch of pgfkeys@unknown, message expandafterunexpandedexpandafter{meaningpgfkeys@code}% introduces an expandafter, which becomes the first expandafter of pgfkeys@unknown. Further patches of pgfkeys@unknown are therefore done in this place. The solution is to replace the offending message by expandonce{meaningpgfkeys@code}%. The full code of the patch command is as follows:

trace@patchcmd@tpgfkverbose@tpgfkpgfkeys@unknown{expandafter}{%

 Unknown handler code:\%

 expandonce{meaningpgfkeys@code}%

}