# The TikZ pipeline: relative order of rendering of pre-actions and 'behind path' nodes

I'm interested in the TikZ pipeline, i.e. the sequence of low-level actions that a TikZ path is converted to as it is being "executed". Unfortunately, this is described only fragmentarily in the TikZ & PGF manual (for version 3.0.1a), so there is no escape from rolling up the metaphoric sleeves and diving into the source code. According to this comment by Mark Wibrow, the pipeline is implemented by the \tikz@finish macro in <tex installation directory>/tex/generic/pgf/frontendlayer/tikz/tikz.code.tex.

The \tikz@finish macro has the following structure:

  % Step 1: The path background box

...

% Step 2: Decorate path

...

% Step 3: Preactions

...

...

% Step 13: Add labels and nodes

...


As can be seen, the pre-actions are applied before any node is inserted. However, the manual states in the description of the node option /tikz/behind path on p. 215:

When this key is set, [...] TikZ collects all nodes defined on the current path with this option set and then inserts all of them, in the order they appear, just before it draws the path. [...] "Just before it draws the path” actually means that the nodes are inserted into the page output just before any pre-actions are applied to the path

There seems to be a discrepancy between the manual and the source code. Is this a bug in the manual, or am I missing something?

• /tikz/behind path sets the \tikz@figbox@bg which is used in step 1. There is no discrepancy. – cfr Aug 3 '17 at 21:41
• @cfr: To me it looks like all it does is give the \tikz@figbox@bg macro the alias \tikz@whichbox: the only place in the file that the string 'behind path' appears is line 901: behind path/.code=\def\tikz@whichbox{\tikz@figbox@bg}. – Evan Aad Aug 3 '17 at 22:01
• Which makes the difference. It means the stuff sent to the \tikz@whichbox ends up in \tikz@figbox@bg as opposed to the default \tikz@figbox. You can see from the order that makes a crucial difference to where the stuff ends up. – cfr Aug 3 '17 at 22:05

There is no discrepancy or mystery here. As the code makes clear, the contents of \tikz@figbox@bg is used before anything else is done (step 1), and behind path ensures that the node in question ends up in this box.

To see the effect, we can simply redefine behind path to use \tikz@figbox (the default) instead.

\documentclass[border=10pt]{standalone}
\usepackage{tikz}
\begin{document}
\begin{tikzpicture}
\draw [draw=blue, fill=blue, fill opacity=.5] (0,0) -| (1,1) node [behind path, fill=yellow, opacity=1, text=red] {behind path} -| cycle;
\begin{scope}[yshift=-15mm, behind path/.code={\def\tikz@whichbox{\tikz@figbox}}]
\draw [draw=blue, fill=blue, fill opacity=.5] (0,0) -| (1,1) node [behind path, fill=yellow, opacity=1, text=red] {behind path} -| cycle;
\end{scope}
\end{tikzpicture}
\end{document}