summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-base-scopes.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-base-scopes.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-base-scopes.tex1027
1 files changed, 1027 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-base-scopes.tex b/graphics/pgf/base/doc/pgfmanual-en-base-scopes.tex
new file mode 100644
index 0000000000..070bfffc05
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-base-scopes.tex
@@ -0,0 +1,1027 @@
+% Copyright 2019 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[Hierarchical Structures: Package, Environments, Scopes, and Text]
+ {Hierarchical Structures:\\
+ Package, Environments, Scopes, and Text}
+
+\subsection{Overview}
+
+\pgfname\ uses two kinds of hierarchical structuring: First, the package itself
+is structured hierarchically, consisting of different packages that are built
+on top of each other. Second, \pgfname\ allows you to structure your graphics
+hierarchically using environments and scopes.
+
+
+\subsubsection{The Hierarchical Structure of the Package}
+
+The \pgfname\ system consists of several layers:
+%
+\begin{description}
+ \item[System layer.]
+ The lowest layer is called the \emph{system layer}, though it might
+ also be called ``driver layer'' or perhaps ``backend layer''. Its job
+ is to provide an abstraction of the details of which driver is used to
+ transform the |.dvi| file. The system layer is implemented by the
+ package |pgfsys|, which will load appropriate driver files as needed.
+
+ The system layer is documented in Part~\ref{part-system}.
+ \item[Basic layer.]
+ The basic layer is loaded by the package |pgfcore| and subsequent use
+ of the command |\usepgfmodule| to load additional modules of the basic
+ layer.
+
+ The basic layer is documented in the present part.
+ \item[Frontend layer.]
+ The frontend layer is not loaded by a single package. Rather, different
+ packages, like \tikzname\ or \textsc{pgfpict2e}, are different
+ frontends to the basic layer.
+
+ The \tikzname\ frontend is documented in Part~\ref{part-tikz}.
+\end{description}
+
+Each layer will automatically load the necessary files of the layers below it.
+
+In addition to the packages of these layers, there are also some library
+packages. These packages provide additional definitions of things like new
+arrow tips or new plot handlers.
+
+The library packages are documented in Part~\ref{part-libraries}.
+
+
+\subsubsection{The Hierarchical Structure of Graphics}
+
+Graphics in \pgfname\ are typically structured hierarchically. Hierarchical
+structuring can be used to identify groups of graphical elements that are to be
+treated ``in the same way''. For example, you might group together a number of
+paths, all of which are to be drawn in red. Then, when you decide later on that
+you like them to be drawn in, say, blue, all you have to do is to change the
+color once.
+
+The general mechanism underlying hierarchical structuring is known as
+\emph{scoping} in computer science. The idea is that all changes to the general
+``state'' of the graphic that are done inside a scope are local to that scope.
+So, if you change the color inside a scope, this does not affect the color used
+outside the scope. Likewise, when you change the line width in a scope, the
+line width outside is not changed, and so on.
+
+There are different ways of starting and ending scopes of graphic parameters.
+Unfortunately, these scopes are sometimes ``in conflict'' with each other and
+it is sometimes not immediately clear which scopes apply. In essence, the
+following scoping mechanisms are available:
+%
+\begin{enumerate}
+ \item The ``outermost'' scope supported by \pgfname\ is the |{pgfpicture}|
+ environment. All changes to the graphic state done inside a
+ |{pgfpicture}| are local to that picture.
+
+ In general, it is \emph{not} possible to set graphic parameters
+ globally outside any |{pgfpicture}| environments. Thus, you can
+ \emph{not} say |\pgfsetlinewidth{1pt}| at the beginning of your
+ document to have a default line width of one point. Rather, you have to
+ (re)set all graphic parameters inside each |{pgfpicture}|. (If this is
+ too bothersome, try defining some macro that does the job for you.)
+ \item Inside a |{pgfpicture}| you can use a |{pgfscope}| environment to
+ keep changes of the graphic state local to that environment.
+
+ The effect of commands that change the graphic state are local to the
+ current |{pgfscope}|, but not always to the current \TeX\ group. Thus,
+ if you open a \TeX\ group (some text in curly braces) inside a
+ |{pgfscope}|, and if you change, for example, the dash pattern, the
+ effect of this changed dash pattern will persist till the end of the
+ |{pgfscope}|.
+
+ Unfortunately, this is not always the case. \emph{Some} graphic
+ parameters only persist till the end of the current \TeX\ group. For
+ example, when you use |\pgfsetarrows| to set the arrow tip inside a
+ \TeX\ group, the effect lasts only till the end of the current \TeX\
+ group.
+ \item Some graphic parameters are not scoped by |{pgfscope}| but
+ ``already'' by \TeX\ groups. For example, the effect of coordinate
+ transformation commands is always local to the current \TeX\ group.
+
+ Since every |{pgfscope}| automatically creates a \TeX\ group, all
+ graphic parameters that are local to the current \TeX\ group are also
+ local to the current |{pgfscope}|.
+ \item Some graphic parameters can only be scoped using \TeX\ groups, since
+ in some situations it is not possible to introduce a |{pgfscope}|. For
+ example, a path always has to be completely constructed and used in the
+ same |{pgfscope}|. However, we might wish to have different coordinate
+ transformations apply to different points on the path. In this case, we
+ can use \TeX\ groups to keep the effect local, but we could not use
+ |{pgfscope}|.
+ \item The |\pgftext| command can be used to create a scope in which \TeX\
+ ``escapes back'' to normal \TeX\ mode. The text passed to the
+ |\pgftext| is ``heavily guarded'' against having any effect on the
+ scope in which it is used. For example, it is possible to use another
+ |{pgfpicture}| environment inside the argument of |\pgftext|.
+\end{enumerate}
+
+Most of the complications can be avoided if you stick to the following
+rules:
+%
+\begin{itemize}
+ \item Give graphic commands only inside |{pgfpicture}| environments.
+ \item Use |{pgfscope}| to structure graphics.
+ \item Do not use \TeX\ groups inside graphics, \emph{except} for keeping
+ the effect of coordinate transformations local.
+\end{itemize}
+
+
+\subsection{The Hierarchical Structure of the Package}
+
+Before we come to the structuring commands provided by \pgfname\ to structure
+your graphics, let us first have a look at the structure of the package itself.
+
+
+\subsubsection{The Core Package}
+
+To use \pgfname, include the following package:
+
+\begin{package}{pgfcore}
+ This package loads the complete core of the ``basic layer'' of \pgfname,
+ but not any modules. That is, it will load all of the commands described in
+ the current part of this manual, but it will not load frontends like
+ \tikzname. It will also load the system layer. To load additional modules,
+ use the |\usepgfmodule| command explained below.
+\end{package}
+
+The following package is just a convenience.
+
+\begin{package}{pgf}
+ This package loads the |pgfcore| and the two modules |shapes| and |plot|.
+
+ In \LaTeX, the package takes two options:
+ %
+ \begin{packageoption}{draft}
+ When this option is set, all images will be replaced by empty
+ rectangles. This can speedup compilation.
+ \end{packageoption}
+
+ \begin{packageoption}{version=\meta{version}}
+ Indicates that the commands of version \meta{version} need to be
+ defined. If you set \meta{version} to |0.65|, then a large bunch of
+ ``compatibility commands'' are loaded. If you set \meta{version} to
+ |0.96|, then these compatibility commands will not be loaded.
+
+ If this option is not given at all, then the commands of all versions
+ are defined.
+ \end{packageoption}
+\end{package}
+
+
+\subsubsection{The Modules}
+
+\begin{command}{\usepgfmodule\marg{module names}}
+ Once the core has been loaded, you can use this command to load further
+ modules. The modules in the \meta{module names} list should be separated by
+ commas. Instead of curly braces, you can also use square brackets, which is
+ something Con\TeX t users will like. If you try to load a module a second
+ time, nothing will happen.
+
+ \example |\usepgfmodule{matrix,shapes}|
+
+ What this command does is to load the file
+ |pgfmodule|\meta{module}|.code.tex| for each \meta{module} in the list of
+ \meta{module names}. Thus, to write your own module, all you need to do is
+ to place a file of the appropriate name somewhere \TeX\ can find it.
+ \LaTeX, plain \TeX, and Con\TeX t users can then use your library.
+\end{command}
+
+The following modules are available for use with |pgfcore|: \todosp{In the
+meantime there are some more modules. Also mention them here?}
+%
+\begin{itemize}
+ \item The |plot| module provides commands for plotting functions. The
+ commands are explained in Section~\ref{section-plots}.
+ \item The |shapes| module provides commands for drawing shapes and nodes.
+ These commands are explained in Section~\ref{section-shapes}.
+ \item The |decorations| module provides commands for adding decorations to
+ paths. These commands are explained in
+ Section~\ref{section-base-decorations}.
+ \item The |matrix| module provides the |\pgfmatrix| command. The commands
+ are documented in Section~\ref{section-base-matrices}.
+\end{itemize}
+
+
+\subsubsection{The Library Packages}
+
+There is a special command for loading library packages. The difference between
+a library and module is the following: A library just defines additional
+objects using the basic layer, whereas a module adds completely new
+functionality. For instance, a |decorations| library defines additional
+decorations, while a decoration module defines the whole code for handling
+decorations.
+
+\begin{command}{\usepgflibrary\marg{list of libraries}}
+ Use this command to load further libraries. The list of libraries should
+ contain the names of libraries separated by commas. Instead of curly
+ braces, you can also use square brackets. If you try to load a library a
+ second time, nothing will happen.
+
+ \example |\usepgflibrary{arrows}|
+
+ This command causes the file |pgflibrary|\meta{library}|.code.tex| to be
+ loaded for each \meta{library} in the \meta{list of libraries}. This means
+ that in order to write your own library file, place a file of the
+ appropriate name somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and
+ Con\TeX t users can then use your library.
+
+ You should also consider adding a \tikzname\ library that simply includes
+ your \pgfname\ library.
+\end{command}
+
+
+\subsection{The Hierarchical Structure of the Graphics}
+
+\subsubsection{The Main Environment}
+
+Most, but not all, commands of the \pgfname\ package must be given within a
+|{pgfpicture}| environment. The only commands that (must) be given outside are
+commands having to do with including images (like |\pgfuseimage|) and with
+inserting complete shadings (like |\pgfuseshading|). However, just to keep life
+entertaining, the |\pgfshadepath| command must be given \emph{inside} a
+|{pgfpicture}| environment.
+
+\begin{environment}{{pgfpicture}}
+ This environment will insert a \TeX\ box containing the graphic drawn by
+ the \meta{environment contents} at the current position.
+
+
+ \medskip
+ \textbf{The size of the bounding box.}
+ The size of the box is determined in the following manner: While \pgfname\
+ parses the \meta{environment contents}, it keeps track of a bounding box
+ for the graphic. Essentially, this bounding box is the smallest box that
+ contains all coordinates mentioned in the graphics. Some coordinates may be
+ ``mentioned'' by \pgfname\ itself; for example, when you add circle to the
+ current path, the support points of the curve making up the circle are also
+ ``mentioned'' despite the fact that you will not ``see'' them in your code.
+
+ Once the \meta{environment contents} have been parsed completely, a \TeX\
+ box is created whose size is the size of the computed bounding box and this
+ box is inserted at the current position.
+ %
+\begin{codeexample}[]
+Hello \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture} World!
+\end{codeexample}
+
+ Sometimes, you may need more fine-grained control over the size of the
+ bounding box. For example, the computed bounding box may be too large or
+ you intensionally wish the box to be ``too small''. In these cases, you can
+ use the command |\pgfusepath{use as bounding box}|, as described in
+ Section~\ref{section-using-bb}.
+
+
+ \medskip
+ \textbf{The baseline of the bounding box.}
+ When the box containing the graphic is inserted into the normal text, the
+ baseline of the graphic is normally at the bottom of the graphic. For this
+ reason, the following two sets of code lines have the same effect, despite
+ the fact that the second graphic uses ``higher'' coordinates than the
+ first:
+ %
+\begin{codeexample}[]
+Rectangles \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture} and \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture}.
+\end{codeexample}
+
+ You can change the baseline using the |\pgfsetbaseline| command, see below.
+ %
+\begin{codeexample}[]
+Rectangles \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+ \pgfsetbaseline{0pt}
+\end{pgfpicture} and \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+ \pgfsetbaseline{0pt}
+\end{pgfpicture}.
+\end{codeexample}
+
+
+ \medskip
+ \textbf{Including text and images in a picture.}
+ You cannot directly include text and images in a picture. Thus, you should
+ \emph{not} simply write some text in a |{pgfpicture}| or use a command like
+ |\includegraphics| or even |\pgfimage|. In all these cases, you need to
+ place the text inside a |\pgftext| command. This will ``escape back'' to
+ normal \TeX\ mode, see Section~\ref{section-text-command} for details.
+
+
+ \medskip
+ \textbf{Remembering a picture position for later reference.}
+ After a picture has been typeset, its position on the page is normally
+ forgotten by \pgfname\ and also by \TeX. This means that is not possible to
+ reference a node in this picture later on. In particular, it is normally
+ impossible to draw lines between nodes in different pictures automatically.
+
+ In order to make \pgfname\ ``remember'' a picture, the \TeX-if
+ |\ifpgfrememberpicturepositiononpage| should be set to |true|. It is only
+ important that this \TeX-if is |true| at the end of the
+ |{pgfpicture}|-en\-vi\-ron\-ment, so you can switch it on inside the
+ environment. However, you can also just switch it on globally, then the
+ positions of all pictures are remembered.
+
+ There are several reasons why the remembering is not switched on by
+ default. First, it does not work for all backend drivers (currently, it
+ works only for pdf\TeX). Second, it requires two passes of \TeX\ over the
+ file; on the first pass all positions will be wrong. Third, for every
+ remembered picture a line is added to the |.aux|-file, which may result in
+ a large number of extra lines.
+
+ Despite all these ``problems'', for documents that are processed with
+ pdf\TeX\ and in which there is only a small number of pictures (less than a
+ hundred or so), you can switch on this option globally, it will not cause
+ any significant slowing of \TeX.
+\end{environment}
+
+\begin{plainenvironment}{{pgfpicture}}
+ The plain \TeX\ version of the environment. Note that in this version,
+ also, a \TeX\ group is created around the environment.
+\end{plainenvironment}
+
+\begin{contextenvironment}{{pgfpicture}}
+ This is the Con\TeX t version of the environment.
+\end{contextenvironment}
+
+{\let\ifpgfrememberpicturepositiononpage=\relax
+\begin{command}{\ifpgfrememberpicturepositiononpage}
+ Determines whether the position of pictures on the page should be recorded.
+ The value of this \TeX-if at the end of a |{pgfpicture}| environment is
+ important, not the value at the beginning.
+
+ If this option is set to true of a picture, \pgfname\ will attempt to
+ record the position of the picture on the page. (This attempt will fail
+ with most drivers and when it works, it typically requires two runs of
+ \TeX.) The position is not directly accessible. Rather, the nodes mechanism
+ will use this position if you access a node from another picture. See
+ Sections~\ref{section-cross-pictures-pgf}
+ and~\ref{section-cross-picture-tikz} for more details.
+\end{command}
+}
+
+\makeatletter
+\begin{command}{\pgfsetbaseline\marg{dimension}}
+ This command specifies a $y$-coordinate of the picture that should be used
+ as the baseline of the whole picture. When a \pgfname\ picture has been
+ typeset completely, \pgfname\ must decide at which height the baseline of
+ the picture should lie. Normally, the baseline is set to the $y$-coordinate
+ of the bottom of the picture, but it is often desirable to use a different
+ height.
+ %
+\begin{codeexample}[]
+Text
+\begin{pgfpicture}
+ \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
+\end{pgfpicture},
+\begin{pgfpicture}
+ \pgfsetbaseline{0pt}
+ \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
+\end{pgfpicture},
+\begin{pgfpicture}
+ \pgfsetbaseline{.5ex}
+ \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
+\end{pgfpicture},
+\begin{pgfpicture}
+ \pgfsetbaseline{-1ex}
+ \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
+\end{pgfpicture}.
+\end{codeexample}
+ %
+\end{command}
+
+\begin{command}{\pgfsetbaselinepointnow\marg{point}}
+ This command specifies the baseline indirectly, namely as the
+ $y$-coordinate that the given \meta{point} has when the command is called.
+\end{command}
+
+\begin{command}{\pgfsetbaselinepointlater\marg{point}}
+ This command also specifies the baseline indirectly, but the $y$-coordinate
+ of the given \meta{point} is only computed at the end of the picture.
+ %
+\begin{codeexample}[]
+Hello
+\begin{pgfpicture}
+ \pgfsetbaselinepointlater{\pgfpointanchor{X}{base}}
+ % Note: no shape X, yet
+ \pgfnode{cross out}{center}{world.}{X}{\pgfusepath{stroke}}
+\end{pgfpicture}
+\end{codeexample}
+ %
+\end{command}
+
+
+\subsubsection{Graphic Scope Environments}
+
+Inside a |{pgfpicture}| environment you can substructure your picture using the
+following environment:
+
+\begin{environment}{{pgfscope}}
+ All changes to the graphic state done inside this environment are
+ local to the environment. The graphic state includes the following:
+ %
+ \begin{itemize}
+ \item The line width.
+ \item The stroke and fill colors.
+ \item The dash pattern.
+ \item The line join and cap.
+ \item The miter limit.
+ \item The canvas transformation matrix.
+ \item The clipping path.
+ \end{itemize}
+ %
+ Other parameters may also influence how graphics are rendered, but they are
+ \emph{not} part of the graphic state. For example, the arrow tip kind is
+ not part of the graphic state and the effect of commands setting the arrow
+ tip kind are local to the current \TeX\ group, not to the current
+ |{pgfscope}|. However, since |{pgfscope}| starts and ends a \TeX\ group
+ automatically, a |{pgfscope}| can be used to limit the effect of, say,
+ commands that set the arrow tip kind.
+ %
+\begin{codeexample}[]
+\begin{pgfpicture}
+ \begin{pgfscope}
+ {
+ \pgfsetlinewidth{2pt}
+ \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{2ex}}
+ \pgfusepath{stroke}
+ }
+ \pgfpathrectangle{\pgfpoint{3ex}{0ex}}{\pgfpoint{2ex}{2ex}}
+ \pgfusepath{stroke}
+ \end{pgfscope}
+ \pgfpathrectangle{\pgfpoint{6ex}{0ex}}{\pgfpoint{2ex}{2ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{pgfpicture}
+ \begin{pgfscope}
+ {
+ \pgfsetarrows{->}
+ \pgfpathmoveto{\pgfpointorigin}\pgfpathlineto{\pgfpoint{2ex}{2ex}}
+ \pgfusepath{stroke}
+ }
+ \pgfpathmoveto{\pgfpoint{3ex}{0ex}}\pgfpathlineto{\pgfpoint{5ex}{2ex}}
+ \pgfusepath{stroke}
+ \end{pgfscope}
+ \pgfpathmoveto{\pgfpoint{6ex}{0ex}}\pgfpathlineto{\pgfpoint{8ex}{2ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture}
+\end{codeexample}
+
+ At the start of the scope, the current path must be empty, that is, you
+ cannot open a scope while constructing a path.
+
+ It is usually a good idea \emph{not} to introduce \TeX\ groups inside a
+ |{pgfscope}| environment.
+\end{environment}
+
+\begin{plainenvironment}{{pgfscope}}
+ Plain \TeX\ version of the |{pgfscope}| environment.
+\end{plainenvironment}
+
+\begin{contextenvironment}{{pgfscope}}
+ This is the Con\TeX t version of the environment.
+\end{contextenvironment}
+
+The following scopes also encapsulate certain properties of the graphic state.
+However, they are typically not used directly by the user.
+
+\begin{environment}{{pgfinterruptpath}}
+ This environment can be used to temporarily interrupt the construction of
+ the current path. The effect will be that the path currently under
+ construction will be ``stored away'' and restored at the end of the
+ environment. Inside the environment you can construct a new path and do
+ something with it.
+
+ An example application of this environment is the arrow tip caching.
+ Suppose you ask \pgfname\ to use a specific arrow tip kind. When the arrow
+ tip needs to be rendered for the first time, \pgfname\ will ``cache'' the
+ path that makes up the arrow tip. To do so, it interrupts the current path
+ construction and then protocols the path of the arrow tip. The
+ |{pgfinterruptpath}| environment is used to ensure that this does not
+ interfere with the path to which the arrow tips should be attached.
+
+ This command does \emph{not} install a |{pgfscope}|. In particular, it does
+ not call any |\pgfsys@| commands at all, which would, indeed, be dangerous
+ in the middle of a path construction.
+\end{environment}
+
+\begin{plainenvironment}{{pgfinterruptpath}}
+ Plain \TeX\ version of the environment.
+\end{plainenvironment}
+
+\begin{contextenvironment}{{pgfinterruptpath}}
+ Con\TeX t version of the environment.
+\end{contextenvironment}
+
+\begin{environment}{{pgfinterruptpicture}}
+ This environment can be used to temporarily interrupt a |{pgfpicture}|.
+ However, the environment is intended only to be used at the beginning and
+ end of a box that is (later) inserted into a |{pgfpicture}| using
+ |\pgfqbox|. You cannot use this environment directly inside a
+ |{pgfpicture}|.
+ %
+\begin{codeexample}[]
+\begin{pgfpicture}
+ \pgfpathmoveto{\pgfpoint{0cm}{0cm}} % In the middle of path, now
+ \newbox\mybox
+ \setbox\mybox=\hbox{
+ \begin{pgfinterruptpicture}
+ Sub-\begin{pgfpicture} % a subpicture
+ \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
+ \pgfpathlineto{\pgfpoint{1cm}{1cm}}
+ \pgfusepath{stroke}
+ \end{pgfpicture}-picture.
+ \end{pgfinterruptpicture}
+ }
+ \pgfqbox{\mybox}%
+ \pgfpathlineto{\pgfpoint{0cm}{1cm}}
+ \pgfusepath{stroke}
+\end{pgfpicture}\hskip3.9cm
+\end{codeexample}
+ %
+\end{environment}
+
+\begin{plainenvironment}{{pgfinterruptpicture}}
+ Plain \TeX\ version of the environment.
+\end{plainenvironment}
+
+\begin{contextenvironment}{{pgfinterruptpicture}}
+ Con\TeX t version of the environment.
+\end{contextenvironment}
+
+\begin{environment}{{pgfinterruptboundingbox}}
+ This environment temporarily interrupts the computation of the bounding box
+ and sets up a new bounding box. At the beginning of the environment the old
+ bounding box is saved and an empty bounding box is installed. After the
+ environment the original bounding box is reinstalled as if nothing has
+ happened.
+\end{environment}
+
+\begin{plainenvironment}{{pgfinterruptboundingbox}}
+ Plain \TeX\ version of the environment.
+\end{plainenvironment}
+
+\begin{contextenvironment}{{pgfinterruptboundingbox}}
+ Con\TeX t version of the environment.
+\end{contextenvironment}
+
+
+\subsubsection{Inserting Text and Images}
+\label{section-text-command}
+
+Often, you may wish to add normal \TeX\ text at a certain point inside a
+|{pgfpicture}|. You cannot do so ``directly'', that is, you cannot simply write
+this text inside the |{pgfpicture}| environment. Rather, you must pass the text
+as an argument to the |\pgftext| command.
+
+You must \emph{also} use the |\pgftext| command to insert an image or a shading
+into a |{pgfpicture}|.
+
+\begin{command}{\pgftext\opt{\oarg{options}}\marg{text}}
+ This command will typeset \meta{text} in normal \TeX\ mode and insert the
+ resulting box into the |{pgfpicture}|. The bounding box of the graphic will
+ be updated so that all of the text box is inside. By default, the text box
+ is centered at the origin, but this can be changed either by giving
+ appropriate \meta{options} or by applying an appropriate coordinate
+ transformation beforehand.
+
+ The \meta{text} may contain verbatim text. (In other words, the \meta{text}
+ ``argument'' is not a normal argument, but is put in a box and some
+ |\aftergroup| hackery is used to find the end of the box.)
+
+ \pgfname's current (high-level) coordinate transformation is synchronized
+ with the canvas transformation matrix temporarily when the text box is
+ inserted. The effect is that if there is currently a high-level rotation
+ of, say, 30 degrees, the \meta{text} will also be rotated by thirty
+ degrees. If you do not want this effect, you have to (possibly temporarily)
+ reset the high-level transformation matrix.
+
+ The \meta{options} keys are used with the path |/pgf/text/|. The following
+ keys are defined for this path:
+ %
+ \begin{key}{/pgf/text/left}
+ The key causes the text box to be placed such that its left border is
+ on the origin.
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[left] {lovely}}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/text/right}
+ The key causes the text box to be placed such that its right border is
+ on the origin.
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[right] {lovely}}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/text/top}
+ This key causes the text box to be placed such that its top is on the
+ origin. This option can be used together with the |left| or |right|
+ option.
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[top] {lovely}}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[top,right] {lovely}}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/text/bottom}
+ This key causes the text box to be placed such that its bottom is on
+ the origin.
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[bottom] {lovely}}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[bottom,right] {lovely}}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/text/base}
+ This key causes the text box to be placed such that its baseline is on
+ the origin.
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base] {lovely}}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base,right] {lovely}}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/text/at=\meta{point}}
+ Translates the origin (that is, the point where the text is shown) to
+ \meta{point}.
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base,at={\pgfpoint{1cm}{0cm}}] {lovely}}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/text/x=\meta{dimension}}
+ Translates the origin by \meta{dimension} along the $x$-axis.
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base,x=1cm,y=-0.5cm] {lovely}}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/text/y=\meta{dimension}}
+ This key works like the |x| option.
+ \end{key}
+ %
+ \begin{key}{/pgf/text/rotate=\meta{degree}}
+ Rotates the coordinate system by \meta{degree}. This will also rotate
+ the text box.
+ %
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base,x=1cm,y=-0.5cm,rotate=30] {lovely}}
+\end{codeexample}
+ \end{key}
+\end{command}
+
+
+\subsection{Object Identifiers}
+
+Graphical objects can have an \emph{identifier,} which allows you to reference
+the object later on. For instance, you could reference the object as the target
+of a hyperlink (although this capability is not necessarily implemented by
+drivers) or as the target of an animation; indeed, animations always need an
+object identifier to identify the to-be-animated object.
+
+Attaching an identifier to an object is a two-step process:
+%
+\begin{enumerate}
+ \item You call |\pgfuseid{|\meta{id}|}| to choose an id, which is a normal
+ string.
+ \item Next, you call one of several commands like |\pgfidscope| or
+ |\pgftext|, which create an object. This object will have then have the
+ id.
+\end{enumerate}
+
+
+\subsubsection{Commands for Creating Graphic Objects}
+
+The following system level commands create an object with an id:
+%
+\begin{enumerate}
+ \item |\pgfsys@begin@idscope|, which creates a graphic scope.
+ \item |\pgfsys@viewboxmeet| or |\pgfsys@viewboxslice|, which create view
+ boxes,
+ \item |\pgfsys@fill|, |\pgfsys@stroke|, and all other path usage command,
+ \item |\pgfsys@hbox| or |\pgfsys@hboxsynced|, which create text boxes, and
+ \item |\pgfsys@animate...|, which create animations.
+\end{enumerate}
+
+These system layer commands are, in turn, called by the following basic layer
+commands (and, also, by the commands that call them, in turn):
+%
+\begin{itemize}
+ \item |\pgfidscope|, which creates an id scope (see below).
+ \item |\pgfviewboxscope|, which creates a view box.
+ \item |\pgfusepath|, which creates a path.
+ \item |\pgftext| and |\pgfnode| and |\pgfmultipartnode|, which create text
+ boxes and nodes, and
+ \item |\pgfanimateattribute|, which creates an animation.
+\end{itemize}
+
+\begin{environment}{{pgfidscope}}
+ Creates a graphic scope that will have the id last used with |\pgfuseid|
+ attached to, provided such an id was set and was not already used with
+ another object. In the latter cases, no graphic scope is created. Thus, if
+ you wish to ensure that a graphic scope is created, you must (additionally)
+ call |\pgfscope| inside or outside the id scope.
+\end{environment}
+
+The Plain\TeX\ and Con\TeX t versions of the environment are:
+%
+\begin{plainenvironment}{{pgfidscope}}
+\end{plainenvironment}
+
+\begin{contextenvironment}{{pgfidscope}}
+\end{contextenvironment}
+
+
+\subsubsection{Settings and Querying Identifiers}
+
+In order to attach an identifier to an object, you first use the following
+command:
+
+\begin{command}{\pgfuseid\marg{name}}
+ The \meta{name} is a string by which the object will be referenced (see
+ |\pgfidrefnextuse|). The next time a graphic object is created in the
+ current \TeX\ scope, the name will be attached to it (actually, it will get
+ a system layer identifier attached to it that is automatically created
+ using |\pgfsys@new@id|, the \meta{name} is bound to that identifier and it
+ can be retrieved using |\pgfidrefnextuse|). This holds true only for the
+ next object: If a second object is created, it will not get the name
+ attached to it. This does not mean, however, that you cannot attach the
+ same name to different objects; you just need to call |\pgfuseid| again
+ before each object.
+
+ Besides the \meta{name} (or, more precisely, besides the system layer
+ identifier it refers to), the current \emph{identifier type} is also
+ important: Actually, a graphic object is not referenced by a system layer
+ identifier, but by the combination of the identifier and a type. You can
+ use the following commands for modifying the type used for the creation of
+ objects:
+
+ \begin{command}{\pgfusetype\marg{type}}
+ Sets the type used for the referencing of graphic objects for the
+ current scope to \meta{type} or, if \meta{type} starts with a dot,
+ appends \meta{type} to the current type.
+
+ You use this command with compound graphic objects: Before each part of
+ a graphic object, set the type to an appropriate value. Now, if the
+ object is named using |\pgfuseid|, you can later on access all parts of
+ the compound object using the combination of the \meta{name} used with
+ |\pgfuseid| and the type of the part.
+
+ As an example, this system is used to give you access to the different
+ parts of a node: When you say |\pgfuseid{mynode}| and then create a
+ node, you can use |mynode| with the empty type to reference the
+ graphics scope that encompasses the whole node, but also |mynode|
+ together with the type |background| to access the background path of
+ the node.
+
+ In detail, \pgfname\ uses this command to set the following types:
+ %
+ \begin{itemize}
+ \item Inside the command |\pgfviewboxscope|, the type |.view| is
+ used for the view object.
+ \item Inside the command |\pgfmultipartnode|, the type
+ |.behind background| is used for the scope of drawings behind
+ the background. Similarly, |.before background| and
+ |.behind foreground| and finally |.before foreground| are used
+ with the respective parts of a node.
+ \item Also inside a node, |.background| and |.foreground| are used
+ as types of the background and foreground paths, respectively.
+ \item Finally, inside a node, for each text part, the text part's
+ name is used as a type (so |.text| is used for the main part).
+ \end{itemize}
+
+ In addition, \tikzname\ uses this command in the following
+ situations:
+ %
+ \begin{itemize}
+ \item The type |.path| is used with a named path (named using the
+ |name| key). This is the graphic object you need to reference
+ when you wish to morph a path.
+ \item The type |.path picture| is used with the scope of the
+ optional path picture.
+ \item The type |.path fill| is used with the path used for filling.
+ This is not the same as the normal path in case the path is
+ filled and patterned, for instance.
+ \item The type |.path shade| is used with the path used for shading
+ a path.
+ \end{itemize}
+ \end{command}
+
+ \begin{command}{\pgfpushtype}
+ Pushes the current type on an internal global stack. The idea is to
+ allow you to temporarily change the current type without having to open
+ a \TeX\ scope.
+ \end{command}
+
+ \begin{command}{\pgfpoptype}
+ Restores the most recent type from the internal global stack of types.
+ \end{command}
+\end{command}
+
+\begin{command}{\pgfclearid}
+ Clears the current id (and type) for the local scope.
+\end{command}
+
+\begin{command}{\pgfidrefnextuse\marg{macro}\marg{name}}
+ This command assigns a system layer identifier (the identifier returned by
+ |\pgfsys@new@id|) to the \meta{macro}, namely the one that will be used the
+ \emph{next} time |\pgfuseid| is used. You use this command for ``forward
+ referencing''.
+
+ A typical use case is the following: A key like |whom| for animations uses
+ this command to get the system identifier that will be used for a future
+ object. Then, this identifier can be passed to system layer commands like
+ |\pgfsys@animation@whom|.
+
+ Note that the ``next'' use need not be on the same page (or there may not
+ even be any use at all), in which case the reference will not refer to any
+ object.
+\end{command}
+
+\begin{command}{\pgfidrefprevuse\marg{macro}\marg{name}}
+ Works like |\pgfidrefnextuse|, only it references the most recent
+ \emph{previous} use of the \meta{name}. As for |\pgfidrefnextuse|, the most
+ recent use need not be on the same page.
+\end{command}
+
+\begin{command}{\pgfaliasid\marg{alias}\marg{name}}
+ Creates an alias of a name inside the current \TeX\ scope. After calling
+ this command, you can use \meta{alias} anywhere where you would normally
+ use \meta{name}. Note that the binding between \meta{alias} and \meta{name}
+ is not kept when |\pgfuseid| is used on the \meta{name} (or the
+ \meta{alias}).
+\end{command}
+
+\begin{command}{\pgfgaliasid\marg{1}\marg{2}}
+ Like |\pgfaliasid|, only the alias is set globally.
+\end{command}
+
+\begin{command}{\pgfifidreferenced\marg{name}\marg{then code}\marg{else code}}
+ If \meta{name} has been referenced, \meta{then code} is executed, otherwise
+ \meta{else code}.
+\end{command}
+
+
+\subsection{Resource Description Framework Annotations (RDFa)}
+\label{section-base-rdf}
+
+With certain output formats (in particular, with \textsc{svg}) you can insert
+annotations into the output file following the standard set by the
+\emph{resource description framework} (known as ``\textsc{rdf}'', please
+consult the literature on \textsc{rdf} and \textsc{rdf}a for an introduction to
+resource descriptions and ontologies and their purpose in general). To do so,
+you call one (or several) of the following commands before you call
+|\pgfidscope|. The attributes and values you specify using the commands will
+then be added to the resulting scope (if the driver supports this, which is
+only the case for \textsc{svg} at the moment). As an example, when you write
+%
+\begin{codeexample}[code only]
+\pgfrdfresource{/fruits/apple}
+\pgfidscope
+...
+\pgfendidscope
+\end{codeexample}
+
+in the resulting \textsc{svg} file you get
+%
+\begin{codeexample}[code only]
+<g resource="/fruits/apple">
+ ...
+</g>
+\end{codeexample}
+
+Most of the following commands just set a single attribute for the next id
+scope. In some cases, however, repeated calling of these commands makes sense
+and causes the passed values to accumulate as in the following example:
+%
+\begin{codeexample}[code only]
+\pgfrdfresource{/fruits/apple}
+\pgfrdfproperty{http://foo.com/props/juicy}
+\pgfrdfproperty{http://foo.com/props/green}
+\pgfidscope
+...
+\pgfendidscope
+\end{codeexample}
+
+Now you get:
+%
+\begin{codeexample}[code only]
+<g resource="/fruits/apple"
+ property="http://foo.com/props/juicy http://foo.com/props/green">
+ ...
+</g>
+\end{codeexample}
+
+The following commands ``accumulate'': |\pgfrdfproperty|, |\pgfrdfrel|,
+|\pgfrdfrev| and also the command |\pgfrdftypeof|.
+
+\begin{command}{\pgfrdfabout\marg{text}}
+ Adds the \textsc{rdf} attribute |about="|\meta{text}|"| to the next id
+ scope (please see the \textsc{rdf}a specification for details on the
+ semantics of |about| in the context of the resource description framework).
+\end{command}
+
+The following commands work the same way.
+
+\begin{command}{\pgfrdfcontent\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfdatatype\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfhref\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfinlist}
+\end{command}
+
+\begin{command}{\pgfrdfprefix\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfproperty\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfrel\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfresource\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfrev\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfsrc\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdftypeof\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfvocab\marg{text}}
+\end{command}
+
+
+\subsection{Error Messages and Warnings}
+
+Sometimes, a command inside \pgfname\ may fail. In this case, two commands are
+useful to communicate with the author:
+
+\begin{command}{\pgferror\marg{message}}
+ Stops the processing of the current document and prints out the
+ \meta{message}. In \LaTeX, this will be done using |\PackageError|,
+ otherwise |\errmessage| is used directly.
+\end{command}
+
+\begin{command}{\pgfwarning\marg{message}}
+ Prints the \meta{message} on the output, but does not interrupt the
+ processing. In \LaTeX, this will be done using |\PackageWarning|, otherwise
+ a write to stream $17$ is used.
+\end{command}