Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-pgfsys-protocol.tex

raw
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: