diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-pgfsys-protocol.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-pgfsys-protocol.tex | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-pgfsys-protocol.tex b/graphics/pgf/base/doc/pgfmanual-en-pgfsys-protocol.tex new file mode 100644 index 0000000000..30a1d79cee --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-pgfsys-protocol.tex @@ -0,0 +1,89 @@ +% 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: |