diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex')
| -rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex | 1178 |
1 files changed, 719 insertions, 459 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex index 9d8e999a863..618ff86c66a 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex @@ -9,296 +9,266 @@ \section[Hierarchical Structures: Package, Environments, Scopes, and Text] -{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. +\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: +\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}. + \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. +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. +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. +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: - +\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|. + \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. + \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. +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. + 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} + 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}{\usepgflibrary\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} +\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. -The following modules are available for use with |pgfcore|: + \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}. + \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 decoration -library defines additional decorations, while a decoration module -defines the whole code for handling decorations. +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 decoration 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} + 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. +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. - + 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}} @@ -306,22 +276,21 @@ Hello \begin{pgfpicture} \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: - + 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}} @@ -332,9 +301,8 @@ Rectangles \begin{pgfpicture} \end{pgfpicture}. \end{codeexample} - You can change the baseline using the |\pgfsetbaseline| command, see - below. - + You can change the baseline using the |\pgfsetbaseline| command, see below. + % \begin{codeexample}[] Rectangles \begin{pgfpicture} \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}} @@ -347,79 +315,77 @@ Rectangles \begin{pgfpicture} \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. + + \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. + 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. + 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. + 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. - + 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} @@ -438,19 +404,18 @@ Text \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. + 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. - + 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} @@ -459,42 +424,37 @@ Hello \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: +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. - + 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} @@ -527,63 +487,59 @@ using the following environment: \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. + 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. + 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. + Plain \TeX\ version of the |{pgfscope}| environment. \end{plainenvironment} \begin{contextenvironment}{{pgfscope}} - This is the Con\TeX t version of the environment. + 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. +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. + 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. + Plain \TeX\ version of the environment. \end{plainenvironment} \begin{contextenvironment}{{pgfinterruptpath}} - Con\TeX t version of the environment. + 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}|. - + 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 @@ -602,166 +558,470 @@ user. \pgfusepath{stroke} \end{pgfpicture}\hskip3.9cm \end{codeexample} + % \end{environment} \begin{plainenvironment}{{pgfinterruptpicture}} - Plain \TeX\ version of the environment. + Plain \TeX\ version of the environment. \end{plainenvironment} \begin{contextenvironment}{{pgfinterruptpicture}} - Con\TeX t version of the environment. + 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. + 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. + Plain \TeX\ version of the environment. \end{plainenvironment} \begin{contextenvironment}{{pgfinterruptboundingbox}} - Con\TeX t version of the environment. + 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. +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}|. +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. + 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. + \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/right} - 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. + \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. + \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. + \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}. + \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. + \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. + \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{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 is 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 use 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: +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. + 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. + 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} |