Path suspension

Question

In several different contexts in the TikZ part of the TikZ & PGF manual for version 3.0.1a a temporary suspension of the construction of the current path is mentioned:

The description of the \pgfextra{<code>} command, p. 162

The construction of the path is temporarily suspended and the 〈code〉 is executed. Then, the path construction is resumed.
The description of the \path ... pic path operation, p. 252

When a pic is encountered, the current path is suspended and a new internal scope is started.
The description of the \path ... graph path operation, p. 262

When this command is encountered on a path, the construction of the current path is suspended (similarly to an edge command or a node command). In a local scope, the 〈options〉 are first executed with the key path /tikz/graphs using the following command...

What exactly does this mean?

percusse suggested that this concept can be implemented using the pgfinterruptpath environment described in the PGF part of the manual, on p. 972. Maybe it can, but not naively. Indeed, a naive implementation would translate

\draw (-1,0) graph{ O[red] } -- (1,0);

which renders as

into

  \pgfmoveto{\pgfpoint{-1cm}{0cm}}
  \begin{pgfinterruptpath}
    \pgfsetfillcolor{red}
    \pgfnode{rectangle}{center}{O}{}{\pgfusepath{discard}}
  \end{pgfinterruptpath}
  \pgflineto{\pgfpoint{1cm}{0cm}}
  \pgfusepath{stroke}

which renders as

Observe that in the former picture, the graph is on top of the path, whereas in the latter one, it is vice versa.

It's just saving the tokens built up so far in a macro for later use. — percusse, Jul 31 '17 at 09:07
@percusse: Could you please give me a concrete example? Choose one of the situations where a path would be suspended, and rewrite it in either TikZ or PGF. — Evan Aad, Jul 31 '17 at 09:15
The path is collected in a macro then you \let\pgftemp\tokenlist and do stuff and then restore \pgftemp. There is no mystery. It's just not exposed to the user. — percusse, Jul 31 '17 at 09:20
@percusse: It is no mystery to you because you are a TeX wiz, and you've probably seen it a hundred times, but it is a mystery to me. I need to see it in action to understand what's going on there. — Evan Aad, Jul 31 '17 at 09:25
I've literally gave you the code. When the parser meets a pic or edge or pgfextra it literally does a \let operation and instead of using \pgfusepath it stores it in a macro does whatever needs to be done and continues where it left off. — percusse, Jul 31 '17 at 09:27
@percusse: Thanks, this is helpful. You wrote that when an interruption occurs, the path is collected in a macro, and restored after the interruption has finished executing. Does this mean that the effect is of moving the interruption code before the path construction code? So that <beginning of path><interruption><end of path> becomes <interruption><beginning of path><end of path>? — Evan Aad, Jul 31 '17 at 09:46
Not really, \draw[red] (0,0) -- (1,1) edge[blue, shorten <=1mm] (3,2) -- (2,1);. The smooth line join at the elbow only happens when it is a single path. I've shortened the edge path to make the line join visible. — percusse, Jul 31 '17 at 09:53
I think looking at examples can help you: https://tex.stackexchange.com/a/82449/1952 or https://tex.stackexchange.com/search?q=pgfextra+ — Ignasi, Jul 31 '17 at 13:05
@percusse: I have an issue with your theory. If in fact the path suspension mentioned in passages I quoted above were implemented by enclosing the interrupting part in a pgfinterruptpath environment, or by encapsulating the path built so far in a macro to be expanded after the interrupting part has been executed, the path would be drawn on top of whatever the interrupting part has drawn. However, in practice the path is drawn below the interrupting part. Take for instance the following graph defined in the middle of a path: \draw (-1,0) graph { O[red] } -- (1,0); — Evan Aad, Aug 01 '17 at 07:19
the black path started before the graph. I didn't mention the order so it's not my premise. — percusse, Aug 01 '17 at 07:52
@percusse: But you did mention the order. You wrote: "The path is collected in a macro then you \let\pgftemp\tokenlist and do stuff and then restore \pgftemp." So the "stuff" gets done before \pgftemp is expanded, i.e. before the path is executed. I'm not bringing this up for the sake of correcting an error; my only concern is to understand what the manual means by 'path suspension', and for a while I thought I understood it, but now I'm back to square 1. — Evan Aad, Aug 01 '17 at 08:30
You don't need to understand how Postscript works to draw things in TeX. This is really not your concern. Let it do its thing. Or spare a week to read the internals. You are really trying to understand pages of TeX code with two examples and a paragraph in the manual. That's just waste of time in my opinion. — percusse, Aug 01 '17 at 08:58
\pgfextra, pic and \path graph take different approaches to "path suspension" (which can be seen in the source code) so the use of this phrase in the manual should not be taken to imply the same underlying basic level operations are occurring, but merely a high level description of what is going on. — Mark Wibrow, Aug 01 '17 at 10:45
@MarkWibrow: Thanks. Could you please describe the approach taken by \path graph? — Evan Aad, Aug 01 '17 at 11:17
@MarkWibrow: Thanks! How can a TikZ user influence whether the box will be inserted beforehand or afterwards? — Evan Aad, Aug 01 '17 at 13:52
behind path and in front of path. See 17.2.1 Syntax of the Node Command (pp214-218 in the Manual for Version 3.0.1a) — Mark Wibrow, Aug 01 '17 at 15:17
@percusse: You hinted that path suspension is derived from a similar PostScript operation. I imagine that you meant the saving of the current graphics state on a stack, seeing as in PostScript the graphics state includes the current path. However, in PDF the current path is not part of the graphics state, and therefore cannot be saved and restored. pdftex renders to PDF, so if this is how path suspension works in TikZ, it can't be mapped directly to driver operations. — Evan Aad, Aug 01 '17 at 15:19
@percusse: Does TikZ emulate the PostScript mechanism by maintaining its own path stack? — Evan Aad, Aug 01 '17 at 15:19
@MarkWibrow: Could you please also explain \pgfextra's approach? — Evan Aad, Aug 02 '17 at 10:01

Evan Aad · Accepted Answer · 2017-08-10T10:20:46.677

As Mark Wibrow wrote in a comment, \pgfextra, pic and graph don't all take the same approach to "path suspension". There are two approaches to path suspension: the one taken by \pgfextra, and the one taken by node. The other path components: edge, graph and pic are, in a way, treated by the TikZ "engine" like special kinds of nodes, and, in particular, their approach to "path suspension" is like the one taken by nodes.

The explanations below are very rough approximations to what is actually going on in the source code. The code snippets are for illustration purposes only; they are not copied verbatim from the source code, but are the result of extreme, almost grotesque, simplification of the actual implementation. Those who want to understand how TikZ is really implemented, should read the source code.

The \pgfextra approach

When \pgfextra{<body>} is "executed", the path parser yields control temporarily to the top-level TikZ picture parser. However, this happens without closing any existing TeX scope or starting any new one, and the engine's internal state remains unchanged, so all the internal data structures created so far along the path remain intact as control changes hands.

Once the top-level parser has finished processing <body>, control returns to the path parser, which picks up right after the \pgfextra{<body>} command. As before, this control switch does not involve the creation or destruction of TeX scopes, and does not affect the engine's state.

These explanations can be restated more formally as follows. Suppose the top-level TikZ picture parser is called \tikz@parser and takes one argument (\def\tikz@parser#1{...}), and that the TikZ path parser is called \path@parser. Then the execution of the path

\path <before> \pgfextra{<extra>} <after>;

proceeds as follows.

The path statement expands to

\path@parser <before> \pgfextra{<extra>} <after>;

The path parser scans the input consecutively, so the above line eventually reduces to
```
\path@parser \pgfextra{<extra>} <after>;
```

This expands to

\tikz@parser{<extra>} \path@parser <after>;

The node approach

A node is typeset into a TeX box that is saved to a TeX box register. A node can be saved to one of two boxes: the foreground box or the background box. All the nodes for which the option behind path was specified are appended to the background box, whereas the rest of the nodes are appended to the foreground box.

At the end of the path, the two boxes' contents, consisting of low-level typesetting directives (aka \specials), are written to the dvi file: first the background box, then the normal path, and finally the foreground box.

Paths are processed in textual order. Since nodes and normal path-construction operations can be textually intermixed, it is essential to take precautions that a node's path will not be treated as a natural continuation of the normal path. Therefore, when a node is first processed, a TeX scope is opened, a copy of the current path is saved to a local "private variable", and the current path is reset, i.e. set to the empty path. Similarly, the path options are saved and reset.

When the node has finished typesetting to the appropriate TeX box, the TeX scope is closed, and the saved path and options are restored.

To put it more formally, the execution of the path

\path <before> node <node specification> <after>;

proceeds as follows.

The path statement expands to

\path@parser <before> node <node specification> <after>;

The path parser scans the input consecutively, so the above line eventually reduces to
```
\path@parser node <node specification> <after>;
```

This expands to

\begin{pgfinterruptpath}%
    \def\options{}%
    \ifx<current node is `behind path`>%
        \setbox\bg@box\hbox{\unbox\bg@box<typeset current node per specs>}%
    \else%
        \setbox\fg@box\hbox{\unbox\fg@box<typeset current node per specs>}%
    \fi%
\end{pgfinterruptpath}%
\path@parser<after>;

Note that the pgfinterruptpath environment automatically surrounds its body with a \begingroup ... \endgroup pair.

Path suspension

1 Answers1

Linked