# How do I debug pgfkeys?

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

-
Do you mean something a bit more advanced than the .show value and so forth? You want to "watch it in action"? –  Andrew Stacey Nov 13 '11 at 19:02
@Andrew: Yes, exactly. Like if I defined \def\a#1{\b#1} \def\b#1{\c#1} \def\c#1{d#1} and called \a{x}; \tracingmacros=1 would show each macro's replacement text and its argument, one after the other. I want that for "logical" keys, not literal key-handling macros. –  Ryan Reich Nov 13 '11 at 19:10
Given the deafening silence on this one, and the number of votes, I think you have an opportunity here to provide a very useful tool: a pgfkeys debugging extension. I think that will a few little extra bits of code here and there, you could successfully trace all the important action and not get overwhelmed by the unnecessary stuff. –  Andrew Stacey Nov 26 '11 at 19:31
@Andrew: I was thinking the same thing. I believe this can be achieved by defining some tracing keys with pgfkeys itself, actually, that would get called in the same manner as handlers. I will think more about this in December once the quarter ends. –  Ryan Reich Nov 26 '11 at 23:51
You may take a look into the key filtering suite which ships with pgfkeys.Its purpose it to present EACH key to some "filter" to decide if the key is to be processed. I suppose that you can easily write some sort of "inspection" key. It has advanced support to handle all available key types. –  Christian Feuersänger Feb 9 '12 at 17:29

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

-
In the latest issue of TUGboat (volume 32, number 3) there is an article on '(La)TeX coding standards' and the apparent lack of cooperation among developers. I too, by omission, have been guilty of this. The 'etoolbox' and 'ltxkeys' packages have internal tracing and debugging features. Might it not be better asking the pgf team to consider integrating your code into theirs and acknowledging you? Aside: why does 'add comment' drop my @Ryan Reich? –  Ahmed Musa Feb 9 '12 at 14:49
Note: Actually, only the \patchcmd command of etoolbox package has the internal tracing utility. –  Ahmed Musa Feb 9 '12 at 15:14
@Ahmed The tracing mode of \patchcmd was actually very useful for me, as it revealed a catcode change I needed to make in order to use it in my setup code. I have tried to imitate its style, in fact. –  Ryan Reich Feb 9 '12 at 18:15
@Ahmed: I have also considered asking the PGF people to support this package. If not by actually merging it, at least by putting in dummy tokens everywhere in their code so it is easier and less fragile to patch in my tracing text. –  Ryan Reich Feb 9 '12 at 22:33
@AhmedMusa Re your aside: If only one user (besides you), i.e. the author of the post, has so far been involved in the comments to the post, it is clear that he or she is the one addressed. And since the post owner is also always notified of comments to their post, the SE system doesn’t deem such an @-notification necessary and removes it. –  doncherry May 2 '13 at 0:40

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

• None so far.
-
Hmm, this could get messy (in terms of replying to stuff)! I admit it was only my first spin with your code and I didn't try all of the gears. ... Idea: have a dedicated chat room for this package. It works well for the Tex-SX stuff (youcould use that one if you like). –  Andrew Stacey Feb 9 '12 at 21:54
Excellent idea! I have created one. –  Ryan Reich Feb 9 '12 at 21:59