[prev] [prev-tail] [tail] [up]

### 35 The Protocol Subsystem

This section describes commands for protocolling literal text created by P G F. 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

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

[prev] [prev-tail] [front] [up]