#23 Integrated implementation of trace-pgfkeys

[Sašo Živanović]

In 2012, Ryan Reich wrote a great little package that traces the execution of keys in pgfkeys. Unfortunately, trace-pgfkeys never saw the light of day at CTAN (it is only available through the author's webpage, http://www.ryancreich.info), the main reason being that it was implemented as a patch against pgfkeys, which made maintenance a nightmare. (And indeed, as pgfkeys internals changed a bit through the years, some tracing features stopped working.)

In agreement with Ryan, I have recently taken over the maintenance of the package, the plan being to integrate its functionality into pgfkeys itself, without patching. The result of this endeavor is this patch proposal.

While the tracing code is integrated into pgfkeys.code.tex, pgfkeys macros are only burdened by it when tracing is enabled. This is achieved by a little utility I have called iftrace, which is a rudimentary implementation of the mechanism proposed in package inlinedef, but does not require LaTeX.

Tracing can be enabled by loading the auxiliary package trace-pgfkeys.sty or, for plain TeX, inputting trace-pgfkeys.tex. (I have prepared trace-pgfkeys for plain TeX and LaTeX, but I'm not sure if anything extra needs to be done for other formats like ConTeXt.) The order of inputting pgfkeys and trace-pgfkeys does not matter: in particular, if the latter is loaded after the former, pgfkeys macros will be redefined to include the tracing code. In this way, (i) the usage pattern from the original trace-pgfkeys remains unchanged, and (ii) tracing the preamble can be easily skipped.

I have taken great care to make the tracing code completely generic (no LaTeX, no eTeX, etc.).

I have performed fairly extensive testing (well, for a one man band) to ensure that loading the tracing code does not disrupt the functionality of pgfkeys. (Due to several bugs, this was not entirely the case for the original package.) In particular, tracing does not disrupt the loading of any pgfkeys-using package from CTAN, including tikz with all libraries, and pgfmanual also compiles without problems, with the resulting pdf identical (according to diffpdf) to the one produced with tracing disabled.

All the codepaths containing tracing info have been tested. There are, however, some pieces of code without tracing info: .search also handler and, most notably, the entire pgfkeysfiltered. These were not traced in the original package and as I have never used either of them, I'm probably ill-suited to add tracing info about them. Hopefully someone else picks up this task.

The output (.log) of the package is identical to the original trace-pgfkeys, modulo bugfixes and one little feature request fulfilled.

As the changes to the original pgfkeys.code.tex (revision 1.38 from CVS) are extensive (essentially every part of the file is changed), I don't attach a patch but rather the new version of the file.

Hopefully, you (the authors of pgf) decide to include the described tracing facilities into mainstream pgfkeys. I would kindly ask for a prompt decision (that's why the increased ticket priority), in particular before making any further changes to pgfkeys. If you find that something more needs to be done before the patch can be accepted, I'm glad to help if I can.