Implement and document pgfkeys tracing.

The tracing code is based on the draft of package
`trace-pgfkeys.sty` (2012/02/06) by Ryan Reich <[email protected]>.

`trace-pgfkeys` had a form of a runtime patch, and was thus difficult to
maintain.  The present implementation integrates the tracing code into
`pgfkeys.code.tex`.  The approach is DocStrip-like: every line of tracing code
occurs behind character `&`, which is set to either catcode 9 (ignore) or 14
(comment) to include or exclude the tracing code, respectively.

Consequently, the tracing code is not loaded unless specifically requested, and
therefore does not slow down normal key processing.

Signed-off-by: Sašo Živanović <[email protected]>

doc/generic/pgf/pgfmanual-en-pgfkeys.tex

@@ -1740,3 +1740,81 @@ \subsection{Error Keys}
 
 
 \input{pgfmanual-en-pgfkeysfiltered.tex}
+
+
+\subsection{Tracing}
+
+\begin{command}{\tracepgfkeys\opt{\oarg{options}}}
+  This command loads the tracing code and starts tracing the execution of
+  |pgfkeys| (if not yet active due to a previous invocation of the command),
+  and applies the given tracing \meta{options}.  Both effects are local to the
+  \TeX\ group.
+
+  The \meta{options} are executed with the key path set to |/trace pgfkeys|.
+  They can be used to change the trace level and the output format.
+
+  The following keys select the trace level; they are listed in order of
+  increasing verbosity:
+  \begin{key}{/trace pgfkeys/silent}
+    This trace level produces no tracing output.  Note that the tracing
+    routines are still executed; once tracing is loaded, key processing will be
+    slower even when the output is silent.
+  \end{key}
+  \begin{key}{/trace pgfkeys/stack}
+    This trace level shows which keys and handlers are executed, and what value
+    they receive.  This is the initial trace level.
+  \end{key}
+  \begin{key}{/trace pgfkeys/trace}
+    In addition to the information shown on the previous trace level, this
+    trace level shows information on key path (de)construction, handlers like
+    |.try|, etc.
+  \end{key}
+  \begin{key}{/trace pgfkeys/verbose}
+    In addition to the information shown on the previous trace level, this
+    trace level shows the code of executed keys and handlers, and provides a
+    running commentary on decisions made during key processing.
+  \end{key}
+
+  The following keys select the output format:
+  \begin{key}{/trace pgfkeys/long}
+    In this format, the tracing info is indented according to the stack call
+    depth.  This is the initial output format.
+  \end{key}
+  \begin{key}{/trace pgfkeys/compact}
+    In this format, the tracing info displays the stack call depth numerically.
+    Use it if the initial long format gets too deep and the lines wrap
+    unpleasantly.
+  \end{key}
+
+\begin{codeexample}[code only]
+  \begingroup
+  % The first invocation of the macro loads the tracing code, making pgfkeys slow.
+  \tracepgfkeys % Implicitly selects stack and long.
+  % When the group closes, the non-tracing pgfkeys code is restored, making pgfkeys fast again.
+  \endgroup
+  \tracepgfkeys[verbose, compact] % Load the tracing code again, and switch to verbose and compact.
+  \tracepgfkeys[silent] % Switch to silent; compact remains in effect. Nothing needs to be loaded.
+\end{codeexample}
+
+  Once the tracing code is loaded, keys residing in |/trace pgfkeys| may be
+  called from any |pgfkeys| processing command, e.g.\ |\tikzset|.  When the
+  tracing code is not loaded, these keys are available but no-ops.
+
+\end{command}
+
+Furthermore, the tracing options may be changed via the following register and
+commands.  When the tracing code is not loaded, these are available but no-ops
+as well.
+
+\begin{command}{\tracingpgfkeys=\meta{trace level}}
+  Select the trace level numerically: 0 = silent, 1 = stack, 2 = trace, 3 =
+  verbose.
+\end{command}
+
+\begin{command}{\tracingpgfkeyslong}
+  Select the long output format.
+\end{command}
+
+\begin{command}{\tracingpgfkeyscompact}
+  Select the compact output format.
+\end{command}