diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-09 00:56:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-09 00:56:57 +0000 |
commit | f07bb53970ee2ecc53f81a206a3d3a67ef665e4a (patch) | |
tree | 6f57a1d62971db79e5ff023bdfd83b22cb971dc9 /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex | |
parent | 007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (diff) |
doc 6
git-svn-id: svn://tug.org/texlive/trunk@85 c570f23f-e606-0410-a88d-b1316a301751
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.tex | 87 |
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: |