35 The Protocol Subsystem

This section describes commands for protocolling literal text created by PGF. The idea is that some literal text, like the string of commands used to draw an arrow head, will be used over and over again in a picture. It is then much more efficient to compute the necessary literal text just once and to quickly insert it “in a single sweep.”

When protocolling is “switched on,” there is a “current protocol” to which literal text gets appended. Once all commands that needed to be protocoled have been issued, the protocol can be obtained and stored using \pgfsysprotocol@getcurrentprotocol. At any point, the current protocol can be changed using a corresponding setting command. Finally, \pgfsysprotocol@invokecurrentprotocol is used to insert the protocoled commands into the .pdf or .dvi file.

Only those \pgfsys@ commands can be protocolled that use the command \pgfsysprotocol@literal interally. For example, the definition of \pgfsys@moveto in pgfsys-common-pdf.def is

All “normal” system-level commands can be protocolled. However, commands for creating or invoking shadings, images, or whole pictures require special \special’s and cannot be protocolled.

\pgfsysprotocol@literalbuffered{<literal text>}

Adds the <literal text> to the current protocol, after it has been “\edefed.” This command will always protocol.

\pgfsysprotocol@literal{<literal text>}

First calls \pgfsysprotocol@literalbuffered on <literal text>. Then, if protocolling is currently switched off, the <literal text> is passed on to \pgfsys@invoke.

\pgfsysprotocol@bufferedtrue

Turns on protocolling. All subsequent calls of \pgfsysprotocol@literal will append their argument to the current protocol.

\pgfsysprotocol@bufferedfalse

Turns off protocolling. Subsequent calls of \pgfsysprotocol@literal directly insert their argument into the current .pdf or .ps.

Note that if the current protocol is not empty when protocolling is switched off, the next call to \pgfsysprotocol@literal will first flush the current protocol, that is, insert it into the file.

\pgfsysprotocol@getcurrentprotocol{<macro name>}

Stores the current protocol in <macro name> for later use.

\pgfsysprotocol@setcurrentprotocol{<macro name>}

Sets the current protocol to <macro name>.

\pgfsysprotocol@invokecurrentprotocol

Inserts the text stored in the current protocol into the .pdf or .dvi file. This does not change the current protocol.

\pgfsysprotocol@flushcurrentprotocol

First inserts the current protocol, then sets the current protocol to the empty string.