36

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

Community
  • 1
Ryan Reich
  • 37,958
  • 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
  • 2
    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 09 '12 at 17:29

2 Answers2

24

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.

Henri Menke
  • 109,596
Ryan Reich
  • 37,958
  • 1
    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 09 '12 at 14:49
  • Note: Actually, only the \patchcmd command of etoolbox package has the internal tracing utility. – Ahmed Musa Feb 09 '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 09 '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 09 '12 at 22:33
  • 1
    @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 02 '13 at 00:40
12

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 \expandafter\unexpanded\expandafter{\meaning\pgfkeys@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{\meaning\pgfkeys@code}%. The full code of the patch command is as follows:

\trace@patchcmd@tpgfk\verbose@tpgfk\pgfkeys@unknown{\expandafter}{%
 Unknown handler code:\\%
 \expandonce{\meaning\pgfkeys@code}%
}
Sašo Živanović
  • 11,732
Ryan Reich
  • 37,958
  • 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 09 '12 at 21:54
  • Excellent idea! I have created one. – Ryan Reich Feb 09 '12 at 21:59
  • As the chat room is not active anymore, I have added the bug report into the answer. I also support the feature request(s) by @AndrewStacey. (The first one about values is actually easy to achieve. I can add the code if anyone's interested.) – Sašo Živanović Apr 27 '16 at 16:14
  • I hope @RyanReich reads this as I believe it's time to put this fantastic package to ctan! – Sašo Živanović Apr 27 '16 at 16:16
  • @SašoŽivanović Thank you. I considered doing this a long time ago but the package is quite version-specific to pgfkeys, and therefore increasingly dated. In addition, these days I don't do any TeX at all. Are you interested in maintaining it? – Ryan Reich Apr 27 '16 at 17:22
  • @RyanReich Yes, I am. Do you have any more material on the package than what I can find on your webpage? If so, please send me an email. – Sašo Živanović Apr 27 '16 at 17:38
  • @SašoŽivanović I actually don't; it's just the .sty file. But please email me with questions; since I never wrote down the answers, they are probably still in my head :) – Ryan Reich Apr 27 '16 at 17:51
  • @RyanReich I will if I'll have any. Care to share your email? --- the umich one on your website doesn't seem to work. – Sašo Živanović Apr 27 '16 at 18:27
  • Oh, right, that one's dead. Use my full name at gmail. – Ryan Reich Apr 27 '16 at 19:39