summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-pgfsys-protocol.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-pgfsys-protocol.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-pgfsys-protocol.tex89
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: