summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex87
1 files changed, 87 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex
new file mode 100644
index 00000000000..53e78421957
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex
@@ -0,0 +1,87 @@
+% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>.
+%
+% This program can be redistributed and/or modified under the terms
+% of the LaTeX Project Public License Distributed from CTAN
+% archives in directory macros/latex/base/lppl.txt.
+
+\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 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
+\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 protocol.
+\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: