☰
PGF/TikZ Manual

The TikZ and PGF Packages
Manual for version 3.1.10

The System Layer

122 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 protocolled 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 protocolled commands into the .pdf or .dvi file.

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


\def\pgfsys@moveto#1#2{\pgfsysprotocol@literal{#1 #2 m}}

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 be protocolled.

  • \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.