diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex | 103 |
1 files changed, 69 insertions, 34 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex index 035e10b1edd..64c9da58f16 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex @@ -9,69 +9,103 @@ \section{Adding libraries to \pgfname: temporary registers} - \label{section-internal-registers} -This section is intended for those who like to write libraries to extend \pgfname. Of course, this requires a good deal of knowledge about \TeX-programming and the structure of the \pgfname\ basic layer. Besides, one will encounter the need of temporary variables and, especially, temporary \TeX\ registers. This section describes how to use a set of pre-allocated temporary registers of the basic layer without needing to allocate more of them. +This section is intended for those who like to write libraries to extend +\pgfname. Of course, this requires a good deal of knowledge about +\TeX-programming and the structure of the \pgfname\ basic layer. Besides, one +will encounter the need of temporary variables and, especially, temporary \TeX\ +registers. This section describes how to use a set of pre-allocated temporary +registers of the basic layer without needing to allocate more of them. -A part of these internals are already mentioned in section~\ref{section-internal-pointcmds}, but the basic layer provides more temporaries than |\pgf@x| and |\pgf@y|. +A part of these internals are already mentioned in +section~\ref{section-internal-pointcmds}, but the basic layer provides more +temporaries than |\pgf@x| and |\pgf@y|. \begin{internallist}[dimen register]{\pgf@x,\pgf@y} - These registers are used to process point coordinates in the basic layer of \pgfname, see section~\ref{section-internal-pointcmds}. After a |\pgfpoint|$\dotsc$ command, they contain the final $x$ and $y$ coordinate, respectively. - - The values of |\pgf@x| and |\pgf@y| are set \emph{globally} in contrast to other available \pgfname\ registers. You should never assume anything about their value unless the context defines them explicitly. + These registers are used to process point coordinates in the basic layer of + \pgfname, see section~\ref{section-internal-pointcmds}. After a + |\pgfpoint|$\dotsc$ command, they contain the final $x$ and $y$ coordinate, + respectively. + The values of |\pgf@x| and |\pgf@y| are set \emph{globally} in contrast to + other available \pgfname\ registers. You should never assume anything about + their value unless the context defines them explicitly. - Please prefer the |\pgf@xa|, |\pgf@xb|, $\dotsc$ registers for temporary dimen registers unless you are writing point coordinate commands. + Please prefer the |\pgf@xa|, |\pgf@xb|, $\dotsc$ registers for temporary + dimen registers unless you are writing point coordinate commands. \end{internallist} \begin{internallist}[dimen register]{ - \pgf@xa, - \pgf@xb, - \pgf@xc, - \pgf@ya, - \pgf@yb, - \pgf@yc} - Temporary registers for \TeX\ dimensions which can be modified freely. Just make sure changes occur only within \TeX\ groups. - - \paragraph{Attention:} - \pgfname\ uses these registers to perform path operations. For reasons of efficiency, path commands do not always guard them. As a consequence, the code + \pgf@xa, + \pgf@xb, + \pgf@xc, + \pgf@ya, + \pgf@yb, + \pgf@yc% +} + Temporary registers for \TeX\ dimensions which can be modified freely. Just + make sure changes occur only within \TeX\ groups. + + \paragraph{Attention:} + % + \pgfname\ uses these registers to perform path operations. For reasons of + efficiency, path commands do not always guard them. As a consequence, the + code + % \begin{codeexample}[code only] \pgfpointadd{\pgfpoint{\pgf@xa}{\pgf@ya}}{\pgfpoint{\pgf@xb}{\pgf@yb}} \end{codeexample} -\noindent -may fail: Inside |\pgfpointadd|, the |\pgf@xa| and friend registers might be -modified. In particular, it might happen that |\pgf@xb| is changed -before |\pgfpoint{\pgf@xb}{\pgf@yb}| is evaluated. The right thing to do -would be to first expand everything using |\edef| and process the values afterwards, -resulting in unnecessary expensive operations. Of course, one can avoid this by simply -looking into the source code of |\pgfpointadd| to see which registers are used. + % + \noindent may fail: Inside |\pgfpointadd|, the |\pgf@xa| and friend + registers might be modified. In particular, it might happen that |\pgf@xb| + is changed before |\pgfpoint{\pgf@xb}{\pgf@yb}| is evaluated. The right + thing to do would be to first expand everything using |\edef| and process + the values afterwards, resulting in unnecessary expensive operations. Of + course, one can avoid this by simply looking into the source code of + |\pgfpointadd| to see which registers are used. \end{internallist} \begin{internallist}[dimen register]{\pgfutil@tempdima,\pgfutil@tempdimb} - Further multi-purpose temporary dimen registers. For \LaTeX, these registers are already allocated as |\@tempdima| and |\@tempdimb| and are simply |\let| to the |\pgfutil@|$\dotsc$ names. + Further multi-purpose temporary dimen registers. For \LaTeX, these + registers are already allocated as |\@tempdima| and |\@tempdimb| and are + simply |\let| to the |\pgfutil@|$\dotsc$ names. \end{internallist} \begin{internallist}[count register]{ - \c@pgf@counta, - \c@pgf@countb, - \c@pgf@countc, - \c@pgf@countd} - These multiple-purpose count registers are used throughout \pgfname\ to perform integer computations. Feel free to use them as well, just make sure changes are scoped by local \TeX\ groups. + \c@pgf@counta, + \c@pgf@countb, + \c@pgf@countc, + \c@pgf@countd% +} + These multiple-purpose count registers are used throughout \pgfname\ to + perform integer computations. Feel free to use them as well, just make sure + changes are scoped by local \TeX\ groups. \end{internallist} \begin{internallist}[openout handle]{\w@pgf@writea} - An |\openout| handle which is used to generate complete output files within locally scoped parts of \pgfname\ (for example, to interact with |gnuplot|). You should always use |\immediate| in front of output operations involving |\w@pgf@writea| and you should always close the file before returning from your code. + An |\openout| handle which is used to generate complete output files within + locally scoped parts of \pgfname\ (for example, to interact with + |gnuplot|). You should always use |\immediate| in front of output + operations involving |\w@pgf@writea| and you should always close the file + before returning from your code. + % \begin{codeexample}[code only] \immediate\openout\w@pgf@writea=myfile.dat \immediate\write\w@pgf@writea{...}% \immediate\write\w@pgf@writea{...}% \immediate\closeout\w@pgf@writea% \end{codeexample} + % \end{internallist} \begin{internallist}[openin handle]{\r@pgf@reada} - An |\openin| handle which is used to read files within locally scoped parts of \pgfname, for example to check if a file exists or to read data files. You should always use |\immediate| in front of output operations involving |\r@pgf@writea| and you should always close the file before returning from your code. + An |\openin| handle which is used to read files within locally scoped parts + of \pgfname, for example to check if a file exists or to read data files. + You should always use |\immediate| in front of output operations involving + |\r@pgf@writea| and you should always close the file before returning from + your code. + % \begin{codeexample}[code only] \immediate\openin\r@pgf@reada=myfile.dat % do something with \macro @@ -84,9 +118,10 @@ looking into the source code of |\pgfpointadd| to see which registers are used. \fi \immediate\closein\r@pgf@reada \end{codeexample} + % \end{internallist} \begin{internallist}[box]{\pgfutil@tempboxa} - A box for temporary use inside of local \TeX\ scopes. For \LaTeX, this box is the same as the already pre-allocated |\@tempboxa|. + A box for temporary use inside of local \TeX\ scopes. For \LaTeX, this box + is the same as the already pre-allocated |\@tempboxa|. \end{internallist} - |