| 1 |
% Copyright 2018 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{The Protocol Subsystem} |
| 12 |
\label{section-protocols} |
| 13 |
|
| 14 |
\makeatletter |
| 15 |
|
| 16 |
This section describes commands for \emph{protocolling} literal text created by |
| 17 |
\pgfname. The idea is that some literal text, like the string of commands used |
| 18 |
to draw an arrow head, will be used over and over again in a picture. It is |
| 19 |
then much more efficient to compute the necessary literal text just once and to |
| 20 |
quickly insert it ``in a single sweep''. |
| 21 |
|
| 22 |
When protocolling is ``switched on'', there is a ``current protocol'' to which |
| 23 |
literal text gets appended. Once all commands that needed to be protocolled |
| 24 |
have been issued, the protocol can be obtained and stored using |
| 25 |
|\pgfsysprotocol@getcurrentprotocol|. At any point, the current protocol can be |
| 26 |
changed using a corresponding setting command. Finally, |
| 27 |
|\pgfsysprotocol@invokecurrentprotocol| is used to insert the protocolled |
| 28 |
commands into the |.pdf| or |.dvi| file. |
| 29 |
|
| 30 |
Only those |\pgfsys@| commands can be protocolled that use the command |
| 31 |
|\pgfsysprotocol@literal| internally. For example, the definition of |
| 32 |
|\pgfsys@moveto| in |pgfsys-common-pdf.def| is |
| 33 |
% |
| 34 |
\begin{codeexample}[code only] |
| 35 |
\def\pgfsys@moveto#1#2{\pgfsysprotocol@literal{#1 #2 m}} |
| 36 |
\end{codeexample} |
| 37 |
% |
| 38 |
All ``normal'' system-level commands can be protocolled. However, commands for |
| 39 |
creating or invoking shadings, images, or whole pictures require special |
| 40 |
|\special|'s and cannot be protocolled. |
| 41 |
|
| 42 |
\begin{command}{\pgfsysprotocol@literalbuffered\marg{literal text}} |
| 43 |
Adds the \meta{literal text} to the current protocol, after it has been |
| 44 |
``|\edef|ed''. This command will always be protocolled. |
| 45 |
\end{command} |
| 46 |
|
| 47 |
\begin{command}{\pgfsysprotocol@literal\marg{literal text}} |
| 48 |
First calls |\pgfsysprotocol@literalbuffered| on \meta{literal text}. Then, |
| 49 |
if protocolling is currently switched off, the \meta{literal text} is |
| 50 |
passed on to |\pgfsys@invoke|. |
| 51 |
\end{command} |
| 52 |
|
| 53 |
\begin{command}{\pgfsysprotocol@bufferedtrue} |
| 54 |
Turns on protocolling. All subsequent calls of |\pgfsysprotocol@literal| |
| 55 |
will append their argument to the current protocol. |
| 56 |
\end{command} |
| 57 |
|
| 58 |
\begin{command}{\pgfsysprotocol@bufferedfalse} |
| 59 |
Turns off protocolling. Subsequent calls of |\pgfsysprotocol@literal| |
| 60 |
directly insert their argument into the current |.pdf| or |.ps|. |
| 61 |
|
| 62 |
Note that if the current protocol is not empty when protocolling is |
| 63 |
switched off, the next call to |\pgfsysprotocol@literal| will first flush |
| 64 |
the current protocol, that is, insert it into the file. |
| 65 |
\end{command} |
| 66 |
|
| 67 |
\begin{command}{\pgfsysprotocol@getcurrentprotocol\marg{macro name}} |
| 68 |
Stores the current protocol in \meta{macro name} for later use. |
| 69 |
\end{command} |
| 70 |
|
| 71 |
\begin{command}{\pgfsysprotocol@setcurrentprotocol\marg{macro name}} |
| 72 |
Sets the current protocol to \meta{macro name}. |
| 73 |
\end{command} |
| 74 |
|
| 75 |
\begin{command}{\pgfsysprotocol@invokecurrentprotocol} |
| 76 |
Inserts the text stored in the current protocol into the |.pdf| or |.dvi| |
| 77 |
file. This does \emph{not} change the current protocol. |
| 78 |
\end{command} |
| 79 |
|
| 80 |
\begin{command}{\pgfsysprotocol@flushcurrentprotocol} |
| 81 |
First inserts the current protocol, then sets the current protocol to the |
| 82 |
empty string. |
| 83 |
\end{command} |
| 84 |
|
| 85 |
|
| 86 |
%%% Local Variables: |
| 87 |
%%% mode: latex |
| 88 |
%%% TeX-master: "pgfmanual" |
| 89 |
%%% End: |