% Copyright 2018 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{The Protocol Subsystem}
\label{section-protocols}

\makeatletter

This section describes commands for \emph{protocolling} literal text created by
\pgfname. 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
%
\begin{codeexample}[code only]
\def\pgfsys@moveto#1#2{\pgfsysprotocol@literal{#1 #2 m}}
\end{codeexample}
%
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.

\begin{command}{\pgfsysprotocol@literalbuffered\marg{literal text}}
    Adds the \meta{literal text} to the current protocol, after it has been
    ``|\edef|ed''. This command will always be protocolled.
\end{command}

\begin{command}{\pgfsysprotocol@literal\marg{literal text}}
    First calls |\pgfsysprotocol@literalbuffered| on \meta{literal text}. Then,
    if protocolling is currently switched off, the \meta{literal text} is
    passed on to |\pgfsys@invoke|.
\end{command}

\begin{command}{\pgfsysprotocol@bufferedtrue}
    Turns on protocolling. All subsequent calls of |\pgfsysprotocol@literal|
    will append their argument to the current protocol.
\end{command}

\begin{command}{\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.
\end{command}

\begin{command}{\pgfsysprotocol@getcurrentprotocol\marg{macro name}}
    Stores the current protocol in \meta{macro name} for later use.
\end{command}

\begin{command}{\pgfsysprotocol@setcurrentprotocol\marg{macro name}}
    Sets the current protocol to \meta{macro name}.
\end{command}

\begin{command}{\pgfsysprotocol@invokecurrentprotocol}
    Inserts the text stored in the current protocol into the |.pdf| or |.dvi|
    file. This does \emph{not} change the current protocol.
\end{command}

\begin{command}{\pgfsysprotocol@flushcurrentprotocol}
    First inserts the current protocol, then sets the current protocol to the
    empty string.
\end{command}


%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End: