From 6f9e1680085e7bb4d258f6f8116369d122e196e1 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Mon, 16 Jan 2023 03:03:27 +0000
Subject: CTAN sync 202301160303

---
 graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex | 1305 +++++++++++++++++++++
 1 file changed, 1305 insertions(+)
 create mode 100644 graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex

(limited to 'graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex')

diff --git a/graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex b/graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex
new file mode 100644
index 0000000000..19499ec551
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-base-nodes.tex
@@ -0,0 +1,1305 @@
+% 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{Nodes and Shapes}
+
+\label{section-shapes}
+
+This section describes the |shapes| module.
+
+\begin{pgfmodule}{shapes}
+    This module defines commands both for creating nodes and for creating
+    shapes. The package is loaded automatically by |pgf|, but you can load it
+    manually if you have  only included |pgfcore|.
+\end{pgfmodule}
+
+
+\subsection{Overview}
+
+\pgfname\ comes with a sophisticated set of commands for creating \emph{nodes}
+and \emph{shapes}. A \emph{node} is a graphical object that consists
+(typically) of (one or more) text labels and some additional stroked or filled
+paths. Each node has a certain \emph{shape}, which may be something simple like
+a |rectangle| or a |circle|, but it may also be something complicated like a
+|uml class diagram| (this shape is currently not implemented, though).
+Different nodes that have the same shape may look quite different, however,
+since shapes (need not) specify whether the shape path is stroked or filled.
+
+
+\subsubsection{Creating and Referencing Nodes}
+
+You create a node by calling the macro |\pgfnode| or the more general
+|\pgfmultipartnode|. This macro takes several parameters and draws the
+requested shape at a certain position. In addition, it will ``remember'' the
+node's position within the current |{pgfpicture}|. You can then, later on,
+refer to the node's position. Coordinate transformations are ``fully
+supported'', which means that if you used coordinate transformations to shift
+or rotate the shape of a node, the node's position will still be correctly
+determined by \pgfname. This is \emph{not} the case if you use canvas
+transformations instead.
+
+
+\subsubsection{Anchors}
+
+An important property of a node or a shape in general are its \emph{anchors}.
+Anchors are ``important'' positions in a shape. For example, the |center|
+anchor lies at the center of a shape, the |north| anchor is usually ``at the
+top, in the middle'' of a shape, the |text| anchor is the lower left corner of
+the shape's text label (if present), and so on.
+
+Anchors are important both when you create a node and when you reference it.
+When you create a node, you specify the node's ``position'' by asking \pgfname\
+to place the shape in such a way that a certain anchor lies at a certain point.
+For example, you might ask that the node is placed such that the |north| anchor
+is at the origin. This will effectively cause the node to be placed below the
+origin.
+
+When you reference a node, you always reference an anchor of the node. For
+example, when you request the ``|north| anchor of the node just placed'' you
+will get the origin. However, you can also request the ``|south| anchor of this
+node'', which will give you a point somewhere below the origin. When a
+coordinate transformation was in force at the time of creation of a node, all
+anchors are also transformed accordingly.
+
+
+\subsubsection{Layers of a Shape}
+
+The simplest shape, the |coordinate|, has just one anchor, namely the |center|,
+and a label (which is usually empty). More complicated shapes like the
+|rectangle| shape also have a \emph{background path}. This is a \pgfname-path
+that is defined by the shape. The shape does not prescribe what should happen
+with the path: When a node is created, this path may be stroked (resulting in a
+frame around the label), filled (resulting in a background color for the text),
+or just discarded.
+
+Although most shapes consist just of a background path plus some label text,
+when a shape is drawn, up to seven different layers are drawn:
+%
+\begin{enumerate}
+    \item The ``behind the background layer''. Unlike the background path,
+        which can be used in different ways by different nodes, the graphic
+        commands given for this layer will always stroke or always fill the
+        path they construct. They might also insert some text that is ``behind
+        everything''.
+    \item The background path layer. How this path is used depends on the
+        arguments of the |\pgfnode| command.
+    \item The ``before the background path layer''. This layer works like the
+        first one, only the commands of this layer are executed after the
+        background path has been used (in whatever way the creator of the node
+        chose).
+    \item The label layer. This layer inserts the node's text box(es).
+    \item The ``behind the foreground layer''. This layer, like the first
+        layer, once more contains graphic commands that are ``simply
+        executed''.
+    \item The foreground path layer. This path is treated in the same way as
+        the background path, only it is drawn after the label text has been
+        drawn.
+    \item The ``before the foreground layer''.
+\end{enumerate}
+
+Which of these layers are actually used depends on the shape.
+
+
+\subsubsection{Node Parts}
+
+A shape typically does not consist only of different background and foreground
+paths, but it may also have text labels. Indeed, for many shapes the text
+labels are the more important part of the shape.
+
+Most shapes will have only one text label. In this case, this text label is
+simply passed as a parameter to the |\pgfnode| command. When the node is drawn,
+the text label is shifted around such that its lower left corner is at the
+|text| anchor of the node.
+
+More complicated shapes may have more than one text label. Nodes of such shapes
+are called \emph{multipart nodes}. The different \emph{node parts} are simply
+the different text labels. For example, a |uml class| shape might have a
+|class name| part, a |method| part and an |attributes| part. Indeed, single
+part nodes are a special case of multipart nodes: They only have one part named
+|text|.
+
+When a shape is declared, you must specify the node parts. There is a simple
+command called |\nodeparts| that takes a list of the part names as input. When
+you create a node of a multipart shape, for each part of the node you must have
+set up a \TeX-box containing the text of the part. For a part named |XYZ| you
+must set up the box |\pgfnodepartXYZbox|. The box will be placed at the anchor
+|XYZ|. See the description of |\pgfmultipartnode| for more details.
+
+
+\subsection{Creating Nodes}
+
+\subsubsection{Creating Simple Nodes}
+
+\begin{command}{\pgfnode\marg{shape}\marg{anchor}\marg{label text}\marg{name}\marg{path usage command}}
+    This command creates a new node. The \meta{shape} of the node must have
+    been declared previously using |\pgfdeclareshape|.
+
+    The shape is shifted such that the \meta{anchor} is at the origin. In order
+    to place the shape somewhere else, use the coordinate transformation prior
+    to calling this command.
+
+    The \meta{name} is a name for later reference. If no name is given, nothing
+    will be ``saved'' for the node, it will just be drawn.
+
+    The \meta{path usage command} is executed for the background and the
+    foreground path (if the shape defines them).
+    %
+\begin{codeexample}[]
+\begin{tikzpicture}
+  \draw[help lines] (0,0) grid (4,3);
+  {
+    \pgftransformshift{\pgfpoint{1.5cm}{1cm}}
+    \pgfnode{rectangle}{north}{Hello World}{hellonode}{\pgfusepath{stroke}}
+  }
+  {
+    \color{red!20}
+    \pgftransformrotate{10}
+    \pgftransformshift{\pgfpoint{3cm}{1cm}}
+    \pgfnode{rectangle}{center}
+      {\color{black}Hello World}{hellonode}{\pgfusepath{fill}}
+  }
+\end{tikzpicture}
+\end{codeexample}
+
+    As can be seen, all coordinate transformations are also applied to the text
+    of the shape. Sometimes, it is desirable that the transformations are
+    applied to the point where the shape will be anchored, but you do not wish
+    the shape itself to be transformed. In this case, you should call
+    |\pgftransformresetnontranslations| prior to calling the |\pgfnode|
+    command.
+    %
+\begin{codeexample}[]
+\begin{tikzpicture}
+  \draw[help lines] (0,0) grid (4,3);
+  {
+    \color{red!20}
+    \pgftransformrotate{10}
+    \pgftransformshift{\pgfpoint{3cm}{1cm}}
+    \pgftransformresetnontranslations
+    \pgfnode{rectangle}{center}
+      {\color{black}Hello World}{hellonode}{\pgfusepath{fill}}
+  }
+\end{tikzpicture}
+\end{codeexample}
+
+    The \meta{label text} is typeset inside the \TeX-box |\pgfnodeparttextbox|.
+    This box is shown at the |text| anchor of the node, if the node has a
+    |text| part. See the description of |\pgfmultipartnode| for details.
+\end{command}
+
+
+\subsubsection{Creating Multi-Part Nodes}
+
+\begin{command}{\pgfmultipartnode\marg{shape}\marg{anchor}\marg{name}\marg{path usage command}}
+    This command is the more general (and less user-friendly) version of the
+    |\pgfnode| command. While the |\pgfnode| command can only be used for
+    shapes that have a single part (which is the case for most shapes), this
+    command can also be used with multi-part nodes.
+
+    When this command is called, for each node part of the node you must have
+    set up one \TeX-box. Suppose the shape has two parts: The |text| part and
+    the |lower| part. Then, prior to calling |\pgfmultipartnode|, you must have
+    set up the boxes |\pgfnodeparttextbox| and |\pgfnodepartlowerbox|. These
+    boxes may contain any \TeX-text. The shape code will then compute the
+    positions of the shape's anchors based on the sizes of the these shapes.
+    Finally, when the node is drawn, the boxes are placed at the anchor
+    positions |text| and |lower|.
+    %
+\begin{codeexample}[preamble={\usetikzlibrary{shapes}}]
+\setbox\pgfnodeparttextbox=\hbox{$q_1$}
+\setbox\pgfnodepartlowerbox=\hbox{01}
+\begin{pgfpicture}
+  \pgfmultipartnode{circle split}{center}{my state}{\pgfusepath{stroke}}
+\end{pgfpicture}
+\end{codeexample}
+
+    \emph{Note:} Be careful when using the |\setbox| command inside a
+    |{pgfpicture}| command. You will have to use |\pgfinterruptpath| at the
+    beginning of the box and |\endpgfinterruptpath| at the end of the box to
+    make sure that the box is typeset correctly. In the above example this
+    problem was sidestepped by moving the box construction outside the
+    environment.
+
+    \emph{Note:} It is not necessary to use |\newbox| for every node part
+    name. Although you need a different box for each part of a single shape,
+    two different shapes may very well use the same box even when the names of
+    the parts are different. Suppose you have a |circle split| shape that has a
+    |lower| part and you have a |uml class| shape that has a |methods| part.
+    Then, in order to avoid exhausting \TeX's limited number of box registers,
+    you can say
+    %
+\begin{codeexample}[code only]
+\newbox\pgfnodepartlowerbox
+\let\pgfnodepartmethodsbox=\pgfnodepartlowerbox
+\end{codeexample}
+    %
+    Also, when you have a node part name with spaces like |class name|, it may
+    be useful to create an alias:
+    %
+\begin{codeexample}[code only]
+\newbox\mybox
+\expandafter\let\csname pgfnodepartclass namebox\endcsname=\mybox
+\end{codeexample}
+    %
+\end{command}
+
+\begin{command}{\pgfcoordinate\marg{name}\marg{coordinate}}
+    This command creates a node of shape |coordinate| at the given
+    \meta{coordinate}. Exactly the same effect can be achieved using first a
+    shift of the coordinate system to \meta{coordinate}, followed by creating a
+    node of shape |coordinate| named \meta{name}. However, this command is
+    easier and more natural to use and, more importantly, it is much faster.
+\end{command}
+
+\begin{command}{\pgfnodealias\marg{new name}\marg{existing node}}
+    This command does not actually create a new node. Rather, it allows you to
+    subsequently access the node \meta{existing node} using the name \meta{new
+    name}.
+\end{command}
+
+\begin{command}{\pgfnoderename\marg{new name}\marg{existing node}}
+    This command renames an existing node.
+\end{command}
+
+There are a number of values that have an influence on the size of a node.
+These values are stored in the following keys.
+
+\begin{key}{/pgf/minimum width=\meta{dimension} (initially 1pt)}
+\keyalias{tikz}
+    This key stores the \emph{recommended} minimum width of a shape. Thus, when
+    a shape is drawn and when the shape's width would be smaller than
+    \meta{dimension}, the shape's width is enlarged by adding some empty space.
+
+    Note that this value is just a recommendation. A shape may choose to ignore
+    this key.
+    %
+\begin{codeexample}[]
+\begin{tikzpicture}
+  \draw[help lines] (-2,0) grid (2,1);
+
+  \pgfset{minimum width=3cm}
+  \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}}
+\end{tikzpicture}
+\end{codeexample}
+    %
+\end{key}
+
+\begin{key}{/pgf/minimum height=\meta{dimension} (initially 1pt)}
+\keyalias{tikz}
+    Works like |/pgf/minimum width|.
+\end{key}
+
+\begin{key}{/pgf/minimum size=\meta{dimension}}
+\keyalias{tikz}
+    This style both |/pgf/minimum width| and |/pgf/minimum height| to \meta{dimension}.
+\end{key}
+
+\begin{key}{/pgf/inner xsep=\meta{dimension} (initially 0.3333em)}
+\keyalias{tikz}
+    This key stores the \emph{recommended} horizontal inner separation between
+    the label text and the background path. As before, this value is just a
+    recommendation and a shape may choose to ignore this key.
+    %
+\begin{codeexample}[]
+\begin{tikzpicture}
+  \draw[help lines] (-2,0) grid (2,1);
+
+  \pgfset{inner xsep=1cm}
+  \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}}
+\end{tikzpicture}
+\end{codeexample}
+    %
+\end{key}
+
+\begin{key}{/pgf/inner ysep=\meta{dimension} (initially 0.3333em)}
+\keyalias{tikz}
+    Works like |/pgf/inner xsep|.
+\end{key}
+
+\begin{key}{/pgf/inner sep=\meta{dimension}}
+\keyalias{tikz}
+    This style sets both |/pgf/inner xsep| and |/pgf/inner ysep| to
+    \meta{dimension}.
+\end{key}
+
+\begin{key}{/pgf/outer xsep=\meta{dimension} (initially .5\string\pgflinewidth)}
+\keyalias{tikz}
+    This key stores the recommended horizontal separation between the
+    background path and the ``outer anchors''. For example, if \meta{dimension}
+    is |1cm| then the |east| anchor will be 1cm to the right of the right
+    border of the background path. As before, this value is just a
+    recommendation.
+    %
+\begin{codeexample}[]
+\begin{tikzpicture}
+  \draw[help lines] (-2,0) grid (2,1);
+
+  \pgfset{outer xsep=.5cm}
+  \pgfnode{rectangle}{center}{Hello World}{x}{\pgfusepath{stroke}}
+
+  \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt}
+  \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt}
+  \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt}
+  \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt}
+  \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt}
+  \pgfusepath{fill}
+\end{tikzpicture}
+\end{codeexample}
+    %
+\end{key}
+
+\begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)}
+\keyalias{tikz}
+    Works like |/pgf/outer xsep|.
+\end{key}
+
+\begin{key}{/pgf/outer sep=\meta{dimension}}
+\keyalias{tikz}
+    This style sets both |/pgf/outer xsep| and |/pgf/outer ysep| to
+    \meta{dimension}.
+\end{key}
+
+
+\subsubsection{Deferred Node Positioning}
+\label{section-shapes-deferred-node-positioning}
+
+Normally, when a node is created using a command like |\pgfnode|, the node is
+immediately inserted into the current picture. In particular, you have no
+chance to change the position of a created node after it has been created.
+Using |\pgfpositionnodelater| in concert with |\pgfpositionnodenow|, you can
+create a node whose position is determined only at some later time.
+
+\begin{command}{\pgfpositionnodelater\marg{macro name}}
+    This command is not a replacement for |\pgfnode|. Rather, when this command
+    is used in a scope, all subsequent node creations in this scope will be
+    affected in the following way:  When a node is created, it is not inserted
+    into the current picture. Instead, it is stored in the box
+    |\pgfpositionnodelaterbox|. Furthermore, the node is not relevant for the
+    picture's bounding box, but a bounding box for the node is computed and
+    stored in the macros |\pgfpositionnodelaterminx| to
+    |\pgfpositionnodelatermaxy|. Then, the \meta{macro name} is called with the
+    following macros set up:
+
+    \begin{command}{\pgfpositionnodelaterbox}
+        A box register number (|0| currently) that stores the node's paths and
+        texts. You should move the contents of this box to a box of your choice
+        inside \meta{macro name}.
+    \end{command}
+
+    \begin{command}{\pgfpositionnodelatername}
+        The name of the just-created-node. This name will be the originally
+        ``desired'' name of the box plus the fixed prefix
+        |not yet positionedPGFINTERNAL|. The idea is to ensure that the
+        original name is not inadvertently used before the node is actually
+        positioned. When |\pgfpositionnodenow| is called, it will change the
+        name to the
+        original name.
+    \end{command}
+
+    \begin{command}{\pgfpositionnodelaterminx}
+        The minimal $x$-position of a bounding box of the node. This bounding
+        box refers to the node when it is positioned with the anchor at the
+        origin. It is guaranteed, that this macro will contain a dimension in
+        the format \meta{number}|pt|.
+    \end{command}
+    %
+    \begin{command}{\pgfpositionnodelaterminy}
+    \end{command}
+    %
+    \begin{command}{\pgfpositionnodelatermaxx}
+    \end{command}
+    %
+    \begin{command}{\pgfpositionnodelatermaxy}
+    \end{command}
+
+    Once a late node has been created, you can add arbitrary code in the same
+    picture. Then, at some later point, you call |\pgfpositionnodenow| to
+    finally position the node at a given position.  At this point, the above
+    macros must have the exact same values they had when \meta{macro name} was
+    called. Note that the above macros are local to a scope that ends right
+    after the call to \meta{macro name}, so it is your job to copy the values
+    to safety inside \meta{macro name}.
+
+    The following two macros will also be set inside the call to \meta{macro
+    name}, but they are only ``informative'' in the sense that you need
+    \emph{not} restore these macros when |\pgfpositionnodenow| is called.
+
+    \begin{command}{\pgfpositionnodelaterpath}
+        This macro stores the path of the background of the node. See
+        Section~\ref{section-soft-paths} for an overview of how these paths are
+        encode.
+    \end{command}
+
+    By setting \meta{macro name} to |\relax| (which is the default), you can
+    switch off the whole mechanism. When a picture is interrupted, this is done
+    automatically.
+\end{command}
+
+\begin{command}{\pgfpositionnodenow\marg{coordinate}}
+    This command is used to position a node that has previously been created
+    using the command |\pgfpositionnodelater|. When |\pgfpositionnodenow| is
+    called, the macros and boxes mentioned in the description of
+    |\pgfpositionnodenow| must be set to the value they had when the
+    \meta{macro name} was called. Provided this is the case, this command will
+    insert the box into the current picture, shifted by \meta{coordinate}.
+    Then, the late code (see below) is called. Subsequently, you can refer to
+    the node with its original name as if it had just been created.
+    %
+\begin{codeexample}[]
+\newbox\mybox
+
+\def\mysaver{
+  \global\setbox\mybox=\box\pgfpositionnodelaterbox
+  \global\let\myname=\pgfpositionnodelatername
+  \global\let\myminx=\pgfpositionnodelaterminx
+  \global\let\myminy=\pgfpositionnodelaterminy
+  \global\let\mymaxx=\pgfpositionnodelatermaxx
+  \global\let\mymaxy=\pgfpositionnodelatermaxy
+}
+
+\begin{tikzpicture}
+  {
+    \pgfpositionnodelater{\mysaver}
+    \node [fill=blue!20,below,rotate=30] (hi) {Hello world};
+  }
+  \draw [help lines] (0,0) grid (3,2);
+
+  \let\pgfpositionnodelatername=\myname
+  \let\pgfpositionnodelaterminx=\myminx
+  \let\pgfpositionnodelaterminy=\myminy
+  \let\pgfpositionnodelatermaxx=\mymaxx
+  \let\pgfpositionnodelatermaxy=\mymaxy
+  \setbox\pgfpositionnodelaterbox=\box\mybox
+  \pgfpositionnodenow{\pgfqpoint{2cm}{2cm}}
+
+  \draw (hi) -- (0,0);
+\end{tikzpicture}
+\end{codeexample}
+    %
+\end{command}
+
+\begin{command}{\pgfnodepostsetupcode\marg{node name}\marg{code}}
+    When you call this macro inside a scope for which the
+    |\pgfpositionnodelater| has been called, the \meta{code} will be stored
+    internally. Later, when the node named \meta{node name} is actually
+    positioned using |\pgfpositionnodenow|, the \meta{code} will be executed.
+    When this macro is called multiple times with the same \meta{node name},
+    the \meta{code} accumulates. However, When |\pgfpositionnodenow| is called,
+    the code stored for the node is cleared.
+
+    The main purpose of this mechanism is to allow \tikzname\ to store
+    so-called ``late options'' with a node that will be positioned only later.
+\end{command}
+
+
+\subsection{Using Anchors}
+
+Each shape defines a set of anchors. We saw already that the anchors are used
+when the shape is drawn: the shape is placed in such a way that the given
+anchor is at the origin (which in turn is typically translated somewhere else).
+
+One has to look up the set of anchors of each shape, there is no ``default''
+set of anchors, except for the |center| anchor, which should always be present.
+Also, most shapes will declare anchors like |north| or |east|, but this is not
+guaranteed.
+
+
+\subsubsection{Referencing Anchors of Nodes in the Same Picture}
+
+Once a node has been defined, you can refer to its anchors using the following
+commands:
+
+\begin{command}{\pgfpointanchor\marg{node}\marg{anchor}}
+    This command is another ``point command'' like the commands described in
+    Section~\ref{section-points}. It returns the coordinate of the given
+    \meta{anchor} in the given \meta{node}. The command can be used in commands
+    like |\pgfpathmoveto|.
+    %
+\begin{codeexample}[]
+\begin{pgfpicture}
+  \pgftransformrotate{30}
+  \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
+
+  \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt}
+  \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt}
+  \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt}
+  \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt}
+  \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt}
+  \pgfusepath{fill}
+\end{pgfpicture}
+\end{codeexample}
+
+    In the above example, you may have noticed something curious: The rotation
+    transformation is still in force when the anchors are invoked, but it does
+    not seem to have an effect. You might expect that the rotation should apply
+    to the already rotated points once more.
+
+    However, |\pgfpointanchor| returns a point that takes the current
+    transformation matrix into account: \emph{The inverse transformation to the
+    current coordinate transformation is applied to an anchor point before
+    returning it.}
+
+    This behavior may seem a bit strange, but you will find it very natural in
+    most cases. If you really want to apply a transformation to an anchor point
+    (for example, to ``shift it away'' a little bit), you have to invoke
+    |\pgfpointanchor| without any transformations in force. Here is an example:
+    %
+\makeatletter
+\begin{codeexample}[pre={\makeatletter}]
+\begin{pgfpicture}
+  \pgftransformrotate{30}
+  \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
+
+  {
+    \pgftransformreset
+    \pgfpointanchor{x}{east}
+    \xdef\mycoordinate{\noexpand\pgfpoint{\the\pgf@x}{\the\pgf@y}}
+  }
+
+  \pgfpathcircle{\mycoordinate}{2pt}
+  \pgfusepath{fill}
+\end{pgfpicture}
+\end{codeexample}
+
+    A special situation arises when the \meta{node} lies in a picture different
+    from the current picture. In this case, if you have not told \pgfname\ that
+    the picture should be ``remembered'', the \meta{node} will be treated as if
+    it lay in the current picture. For example, if the \meta{node} was at
+    position $(3,2)$ in the original picture, it is treated as if it lay at
+    position $(3,2)$ in the current picture. However, if you have told
+    \pgfname\ to remember the picture position of the node's picture and also
+    of the current picture, then |\pgfpointanchor| will return a coordinate
+    that corresponds to the position of the node's anchor on the page,
+    transformed into the current coordinate system. For examples and more
+    details see Section~\ref{section-cross-pictures-pgf}.
+\end{command}
+
+\begin{command}{\pgfpointshapeborder\marg{node}\marg{point}}
+    This command returns the point on the border of the shape that lies on a
+    straight line from the center of the node to \meta{point}. For complex
+    shapes it is not guaranteed that this point will actually lie on the
+    border, it may be on the border of a ``simplified'' version of the shape.
+    %
+\begin{codeexample}[]
+\begin{pgfpicture}
+  \begin{pgfscope}
+    \pgftransformrotate{30}
+    \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
+  \end{pgfscope}
+  \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{2cm}{1cm}}}{2pt}
+  \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt}
+  \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{-1cm}{1cm}}}{2pt}
+  \pgfpathcircle{\pgfpoint{-1cm}{1cm}}{2pt}
+  \pgfusepath{fill}
+\end{pgfpicture}
+\end{codeexample}
+    %
+    \emph{Remark:} If the given \meta{point} is almost identical to the center
+    of \meta{node}, the node center is returned and a warning message will be
+    printed.
+\end{command}
+
+
+\subsubsection{Referencing Anchors of Nodes in Different Pictures}
+\label{section-cross-pictures-pgf}
+
+As a picture is typeset, \pgfname\ keeps track of the positions of all nodes
+inside the picture. What \pgfname\ does not remember is the position of the
+picture \emph{itself} on the page. Thus, if you define a node in one picture
+and then try to reference this node while another picture is typeset, \pgfname\
+will only know the position of the nodes that you try to typeset inside the
+original picture, but it will not know where this picture lies. What is missing
+is the relative positioning of the two pictures.
+
+To overcome this problem, you need to tell \pgfname\ that it should remember
+the position of pictures on a page. If these positions are remembered, then
+\pgfname\ can compute the offset between the pictures and make nodes in
+different pictures accessible.
+
+Determining the positions of pictures on the page is, alas, not-so-easy.
+Because of this, \pgfname\ does not do so automatically. Rather, you have to
+proceed as follows:
+%
+\begin{enumerate}
+    \item You have to use a backend driver that supports position tracking.
+        pdf\TeX\ is one such driver, |dvips| currently is not.
+    \item You have to say |\pgfrememberpicturepositiononpagetrue| somewhere
+        before or inside every picture
+        %
+        \begin{itemize}
+            \item in which you wish to reference a node and
+            \item from which you wish to reference a node in another picture.
+        \end{itemize}
+        %
+        The second item is important since \pgfname\ does not only need to know
+        the position of the picture in which the node you wish to reference
+        lies, but it also needs to know where the current picture lies.
+    \item You typically have to run \TeX\ twice (depending on the backend
+        driver) since the position information typically gets written into an
+        external file on the first run and is available only on the second run.
+    \item You have to switch off automatic bounding bound computations. The
+        reason is that the node in the other picture should not influence the
+        size of the bounding box of the current picture. You should say
+        |\pgfusepath{use as bounding box}| before using a coordinate in another
+        picture.
+\end{enumerate}
+
+
+\subsection{Special Nodes}
+
+There are several special nodes that are always defined and which you should
+not attempt to redefine.
+
+\begin{predefinednode}{current bounding box}
+    This node is of shape |rectangle|. Unlike normal nodes, its size changes
+    constantly and always reflects the size of the bounding box of the current
+    picture. This means that, for instance, that
+    %
+\begin{codeexample}[code only]
+\pgfpointanchor{current bounding box}{south east}
+\end{codeexample}
+    %
+    returns the lower left corner of the bounding box of the current picture.
+\end{predefinednode}
+
+\begin{predefinednode}{current path bounding box}
+    This node is also of shape |rectangle|. Its size is the size of the
+    bounding box of the current path.
+\end{predefinednode}
+
+\begin{predefinednode}{current subpath start}
+    This node is of shape |coordinate| and is at the beginning of the current
+    subpath. This is the position of the last move-to operation.
+\end{predefinednode}
+
+\begin{predefinednode}{current page}
+    This node is inside a virtual remembered picture. The size of this node is
+    the size of the current page. This means that if you create a remembered
+    picture and inside this picture you reference an anchor of this node, you
+    reference an absolute position on the page. To demonstrate the effect, the
+    following code puts some text in the lower left corner of the current page.
+    Note that this works only if the backend driver supports it, otherwise the
+    text is inserted right here.
+    %
+{%
+\pgfrememberpicturepositiononpagetrue%
+\begin{pgfpicture}
+    \pgfusepath{use as bounding box}
+    \pgftransformshift{\pgfpointanchor{current page}{south west}}
+    \pgftransformshift{\pgfpoint{1cm}{1cm}}
+    \pgftext[left,base]{
+        \textcolor{red}{
+            Text absolutely positioned in
+            the lower left corner.}
+    }
+\end{pgfpicture}
+}%
+\begin{codeexample}[code only]
+\pgfrememberpicturepositiononpagetrue
+\begin{pgfpicture}
+  \pgfusepath{use as bounding box}
+  \pgftransformshift{\pgfpointanchor{current page}{south west}}
+  \pgftransformshift{\pgfpoint{1cm}{1cm}}
+  \pgftext[left,base]{
+    \textcolor{red}{
+      Text absolutely positioned in
+      the lower left corner.}
+  }
+\end{pgfpicture}
+\end{codeexample}
+    %
+\end{predefinednode}
+
+There is also an option that allows you to create new special nodes quite
+similar to the above:
+%
+\begin{key}{/pgf/local bounding box=\meta{node name}}
+\keyalias{tikz}
+    This defines a new node \meta{node name} whose size is the bounding box
+    around all objects in the current scope starting at the position where this
+    option was given. After the end of the scope, the \meta{node name} is still
+    available. You can use this option to keep track of the size of a certain
+    area. Note that excessive use of this option (keeping track of dozens of
+    bounding boxes at the same time) will slow things down.
+    %
+\begin{codeexample}[preamble={\usetikzlibrary{scopes}}]
+\begin{tikzpicture}
+  \draw [help lines] (0,0) grid (3,2);
+  { [local bounding box=outer box]
+    \draw (1,1) circle (.5) [local bounding box=inner box] (2,2) circle (.5);
+  }
+  \draw      (outer box.south west) rectangle (outer box.north east);
+  \draw[red] (inner box.south west) rectangle (inner box.north east);
+\end{tikzpicture}
+\end{codeexample}
+    %
+\end{key}
+
+
+\subsection{Declaring New Shapes}
+
+There are only three predefined shapes, see
+Section~\ref{section-predefined-shapes}, so there must be some way of defining
+new shapes. Defining a shape is, unfortunately, a not-quite-trivial process.
+The reason is that shapes need to be both very flexible (their size will vary
+greatly according to circumstances) and they need to be constructed reasonably
+``fast''. \pgfname\ must be able to handle pictures with several hundreds of
+nodes and documents with thousands of nodes in total. It would not do if
+\pgfname\ had to compute and store, say, dozens of anchor positions for every
+node.
+
+
+\subsubsection{What Must Be Defined For a Shape?}
+
+In order to define a new shape, you must provide:
+%
+\begin{itemize}
+    \item a \emph{shape name},
+    \item code for computing the  \emph{saved anchors} and \emph{saved
+    dimensions},
+    \item code for computing \emph{anchor} positions in terms of the saved
+        anchors,
+    \item optionally code for the \emph{background path} and \emph{foreground
+        path},
+    \item optionally code for \emph{things to be drawn before or behind} the
+        background and foreground paths.
+    \item optionally a list of node parts.
+\end{itemize}
+
+
+\subsubsection{Normal Anchors Versus Saved Anchors}
+
+Anchors  are special places in a shape. For example, the |north east| anchor,
+which is a normal anchor, lies at the upper right corner of the |rectangle|
+shape, as does |\northeast|, which is a saved anchor. The difference is the
+following: \emph{saved anchors are computed and stored for each node, anchors
+are only computed as needed.} The user only has access to the normal anchors,
+but a normal anchor can just ``copy'' or ``pass through'' the location of a
+saved anchor.
+
+The idea behind all this is that a shape can declare a very large number of
+normal anchors, but when a node of this shape is created, these anchors are not
+actually computed. However, this causes a problem: When we wish to reference an
+anchor of a node at some later time, we must still be able to compute the
+position of the anchor. For this, we may need a lot of information: What was
+the transformation matrix that was in force when the node was created? What was
+the size of the text box? What were the values of the different separation
+dimensions? And so on.
+
+To solve this problem, \pgfname\ will always compute the locations of all
+\emph{saved anchors} and store these positions. Then, when an normal anchor
+position is requested later on, the anchor position can be given just from
+knowing where the locations of the saved anchors are.
+
+As an example, consider the |rectangle| shape. For this shape two anchors are
+saved: The |\northeast| corner and the |\southwest| corner. A normal anchor
+like |north west| can now easily be expressed in terms of these coordinates:
+Take the $x$-position of the |\southwest| point  and the $y$-position of the
+|\northeast| point. The |rectangle| shape currently defines 13 normal anchors,
+but needs only two saved anchors. Adding new anchors like a  |south south east|
+anchor would not increase the memory and computation requirements of pictures.
+
+All anchors (both saved and normal) are specified in a local \emph{shape
+coordinate space}. This is also true for the background and foreground paths.
+The |\pgfnode| macro will automatically apply appropriate transformations to
+the coordinates so that the shape is shifted to the right anchor or otherwise
+transformed.
+
+
+\subsubsection{Command for Declaring New Shapes}
+
+The following command declares a new shape:
+%
+\begin{command}{\pgfdeclareshape\marg{shape name}\marg{shape specification}}
+    This command declares a new shape named \meta{shape name}. The shape name
+    can later be used in commands like |\pgfnode|.
+
+    The \meta{shape specification} is some \TeX\ code containing calls to
+    special commands that are only defined inside the \meta{shape
+    specification} (similarly to commands like |\draw| that are only available
+    inside the |{tikzpicture}| environment).
+
+    \example Here is the code of the |coordinate| shape:
+    %
+\begin{codeexample}[code only]
+\pgfdeclareshape{coordinate}
+{
+  \savedanchor\centerpoint{%
+    \pgf@x=.5\wd\pgfnodeparttextbox%
+    \pgf@y=.5\ht\pgfnodeparttextbox%
+    \advance\pgf@y by -.5\dp\pgfnodeparttextbox%
+  }
+  \anchor{center}{\centerpoint}
+  \anchorborder{\centerpoint}
+}
+\end{codeexample}
+
+    The special commands are explained next. In the examples given for the
+    special commands a new shape will be constructed, which we might call
+    |simple rectangle|. It should behave like the normal rectangle shape, only
+    without bothering about the fine details like inner and outer separations.
+    The skeleton for the shape is the following.
+    %
+\begin{codeexample}[code only]
+\pgfdeclareshape{simple rectangle}{
+  ...
+}
+\end{codeexample}
+
+    \begin{command}{\nodeparts\marg{list of node parts}}
+        This command declares which parts make up nodes of this shape. A
+        \emph{node part} is a (possibly empty) text label that is drawn when a
+        node of the shape is created.
+
+        By default, a shape has just one node part called |text|. However,
+        there can be several node parts. For example, the |circle split| shape
+        has two parts: the |text| part, which shows that the upper text, and a
+        |lower| part, which shows the lower text. For the |circle split| shape
+        the |\nodeparts| command was called with the argument |{text,lower}|.
+
+        When a multipart node is created, the text labels are drawn in the
+        sequences listed in the \meta{list of node parts}. For each node part,
+        you must have declared one anchor and the \TeX-box of the part is
+        placed at this anchor. For a node part called |XYZ| the \TeX-box
+        |\pgfnodepartXYZbox| is placed at anchor |XYZ|.
+    \end{command}
+
+    \begin{command}{\savedanchor\marg{command}\marg{code}}
+        This command declares a saved anchor. The argument \meta{command}
+        should be a \TeX\ macro name like |\centerpoint|.
+
+        The \meta{code} will be executed each time |\pgfnode| (or
+        |\pgfmultipartnode|) is called to  create a node of the shape
+        \meta{shape name}. When the \meta{code} is executed, the \TeX-boxes of
+        the node parts will contain the text labels of the node. Possibly,
+        these box are void. For example, if there is just a |text| part, the
+        node |\pgfnodeparttextbox| will be set up when the \meta{code} is
+        executed.
+
+        The \meta{code} can use the width, height, and depth of the box(es) to
+        compute the location of the saved anchor. In addition, the \meta{code}
+        can take into account the values of dimensions like |\pgfshapeminwidth|
+        or |\pgfshapeinnerxsep|. Furthermore, the \meta{code} can take into
+        consideration the values of any further shape-specific variables that
+        are set at the moment when |\pgfnode| is called.
+
+        The net effect of the \meta{code} should be to set the two \TeX\
+        dimensions |\pgf@x| and |\pgf@y|. One way to achieve this is to say
+        |\pgfpoint{|\meta{x value}|}{|\meta{y value}|}| at the end of the
+        \meta{code}, but you can also just set these variables. The values that
+        |\pgf@x| and |\pgf@y| have after the code has been executed, let us
+        call them $x$ and $y$, will be recorded and stored together with the
+        node that is created by the command |\pgfnode|.
+
+        The macro \meta{command} is defined to be |\pgfpoint{|$x$|}{|$y$|}|.
+        However, the \meta{command} is only locally defined while anchor
+        positions are being computed. Thus, it is possible to use very simple
+        names for \meta{command}, like |\center| or |\a|, without causing a
+        name-clash. (To be precise, very simple \meta{command} names will clash
+        with existing names, but only locally inside the computation of anchor
+        positions; and we do not need the normal |\center| command during these
+        computations.)
+
+        For our |simple rectangle| shape, we will need only one saved anchor:
+        The upper right corner. The lower left corner could either be the
+        origin or the ``mirrored'' upper right corner, depending on whether we
+        want the text label to have its lower left corner at the origin or
+        whether the text label should be centered on the origin. Either will be
+        fine, for the final shape this will make no difference since the shape
+        will be shifted anyway. So, let us assume that the text label is
+        centered on the origin (this will be specified later on using the
+        |text| anchor). We get the following code for the upper right corner:
+        %
+\begin{codeexample}[code only]
+\savedanchor{\upperrightcorner}{
+  \pgf@y=.5\ht\pgfnodeparttextbox % height of the box, ignoring the depth
+  \pgf@x=.5\wd\pgfnodeparttextbox % width of the box
+}
+\end{codeexample}
+
+        If we wanted to take, say, the |\pgfshapeminwidth| into account, we
+        could use the following code:
+        %
+\begin{codeexample}[code only]
+\savedanchor{\upperrightcorner}{
+  \pgf@y=.\ht\pgfnodeparttextbox % height of the box
+  \pgf@x=.\wd\pgfnodeparttextbox % width of the box
+  \setlength{\pgf@xa}{\pgfshapeminwidth}
+  \ifdim\pgf@x<.5\pgf@xa
+    \pgf@x=.5\pgf@xa
+  \fi
+}
+\end{codeexample}
+        %
+        Note that we could not have written |.5\pgfshapeminwidth| since the
+        minimum width is stored in a ``plain text macro'', not as a real
+        dimension. So if |\pgfshapeminwidth| depth were 2cm, writing
+        |.5\pgfshapeminwidth| would yield the same as |.52cm|.
+
+        In the ``real'' |rectangle| shape the code is somewhat more complex,
+        but you get the basic idea.
+    \end{command}
+    %
+    \begin{command}{\saveddimen\marg{command}\marg{code}}
+        This command is similar to |\savedanchor|, only instead of setting
+        \meta{command} to |\pgfpoint{|$x$|}{|$y$|}|, the \meta{command} is set
+        just to (the value of) $x$.
+
+        In the |simple rectangle| shape we might use a saved dimension to store
+        the depth of the shape box.
+        %
+\begin{codeexample}[code only]
+\saveddimen{\depth}{
+  \pgf@x=\dp\pgfnodeparttextbox
+}
+\end{codeexample}
+    \end{command}
+    %
+    \begin{command}{\savedmacro\marg{command}\marg{code}}
+        This command is similar to |\saveddimen|, only at some point in
+        \meta{code}, \meta{command} should be defined appropriately, (this
+        could be a value, or some text).
+
+        In the |regular polygon| shape, a saved macro is used to store the
+        number of sides of the polygon.
+        %
+\begin{codeexample}[code only]
+\savedmacro{\sides}{\let\sides\pgfpolygonsides}
+\end{codeexample}
+    \end{command}
+    %
+    \begin{command}{\anchor\marg{name}\marg{code}}
+        This command declares an anchor named \meta{name}. Unlike for saved
+        anchors, the \meta{code} will not be executed each time a node is
+        declared. Rather, the \meta{code} is only executed when the anchor is
+        specifically requested; either for anchoring the node during its
+        creation or as a position in the shape referenced later on.
+
+        The \meta{name} is a quite arbitrary string that is not ``passed down''
+        to the system level. Thus, names like |south| or |1| or |::| would all
+        be fine.
+
+        A saved anchor is not automatically also a normal anchor. If you wish
+        to give the users access to a saved anchor you must declare a normal
+        anchor that just returns the position of the saved anchor.
+
+        When the \meta{code} is executed, all saved anchor macros will be
+        defined. Thus, you can reference them in your \meta{code}. The effect
+        of the \meta{code} should be to set the values of |\pgf@x| and |\pgf@y|
+        to the coordinates of the anchor.
+
+        Let us consider some example for the |simple rectangle| shape. First,
+        we would like to make the upper right corner publicly available, for
+        example as |north east|:
+        %
+\begin{codeexample}[code only]
+\anchor{north east}{\upperrightcorner}
+\end{codeexample}
+
+        The |\upperrightcorner| macro will set |\pgf@x| and |\pgf@y| to the
+        coordinates of the upper right corner. Thus, |\pgf@x| and |\pgf@y| will
+        have exactly the right values at the end of the anchor's code.
+
+        Next, let us define a |north west| anchor. For this anchor, we can
+        negate the |\pgf@x| variable:
+        %
+\begin{codeexample}[code only]
+\anchor{north west}{
+  \upperrightcorner
+  \pgf@x=-\pgf@x
+}
+\end{codeexample}
+
+        Finally, it is a good idea to always define a |center| anchor, which
+        will be the default location for a shape.
+        %
+\begin{codeexample}[code only]
+\anchor{center}{\pgfpointorigin}
+\end{codeexample}
+
+        You might wonder whether we should not take into consideration that the
+        node is not placed at the origin, but has been shifted somewhere.
+        However, the anchor positions are always specified in the shape's
+        ``private'' coordinate system. The ``outer'' transformation that has
+        been applied to the shape upon its creation is applied automatically to
+        the coordinates returned by the anchor's \meta{code}.
+
+        Our |simple rectangle| only has one text label (node part) called
+        |text|. This is the default situation, so we do not need to do
+        anything. For the |text| node part we must set up a |text| anchor. Upon
+        creation of a node, this anchor will be made to coincide with the left
+        endpoint of the baseline of the text label (within the private
+        coordinate system of the shape). By default, the |text| anchor is at
+        the origin, but you may change this. For example, we would say
+        %
+\begin{codeexample}[code only]
+\anchor{text}{%
+  \upperrightcorner%
+  \pgf@x=-\pgf@x%
+  \pgf@y=-\pgf@y%
+}
+\end{codeexample}
+        to center the text label on the origin in the shape coordinate space.
+        Note that we could \emph{not} have written the following:
+        %
+\begin{codeexample}[code only]
+\anchor{text}{\pgfpoint{-.5\wd\pgfnodeparttextbox}{-.5\ht\pgfnodeparttextbox}}
+\end{codeexample}
+        %
+        Do you see why this is wrong? The problem is that the box
+        |\pgfnodeparttextbox| will most likely not have the correct size when
+        the anchor is computed. After all, the anchor position might be
+        recomputed at a time when several other nodes have been created.
+
+        If a shape has several node parts, we would have to define an anchor
+        for each part.
+  \end{command}
+
+  \begin{command}{\deferredanchor\marg{name}\marg{code}}
+        This command declares an anchor named \meta{name}. It works like
+        |\anchor|. However, unlike for anchors declared by |\anchor|,
+        \meta{name} will \emph{not} be expanded during the shape declaration
+        (i.e.\ not during |\pgfdeclareshape|). Rather, the \meta{name} is
+        expanded when the \emph{node} is actually used (with |\pgfnode| or more
+        likely with |\node|). This may be useful if the anchor name is context
+        dependent (depending, for example, on the value of a key).
+        %
+\begin{codeexample}[code only]
+\makeatletter
+\def\foo{foo}
+\pgfdeclareshape{simple shape}{%
+  \savedanchor{\center}{%
+    \pgfpointorigin}
+  \anchor{center}{\center}
+  \savedanchor{\anchorfoo}{%
+    \pgf@x=1cm
+    \pgf@y=0cm}
+  \deferredanchor{anchor \foo}{\anchorfoo}}
+
+\begin{tikzpicture}
+  \node[simple shape] (Test1) at (0,0) {};
+  \fill (Test1.anchor foo) circle (2pt) node[below] {anchor foo anchor};
+  %
+  \def\foo{bar}
+  \node[simple shape] (Test2) at (2,2) {};
+  \fill (Test2.anchor bar) circle (2pt) node[below] {anchor bar anchor};
+\end{tikzpicture}
+\end{codeexample}
+    \end{command}
+    %
+    \begin{command}{\anchorborder\marg{code}}
+        A \emph{border anchor} is an anchor point on the border of the shape.
+        What exactly is considered as the ``border'' of the shape depends on
+        the shape.
+
+        When the user requests a point on the border of the shape using the
+        |\pgfpointshapeborder| command, the \meta{code} will be executed to
+        discern this point. When the execution of  the \meta{code} starts, the
+        dimensions |\pgf@x| and |\pgf@y| will have been set to a location $p$
+        in the shape's coordinate system, and relative to the anchor |center|.
+        Note that |\pgfpointshapeborder| will produce an error if the shape does
+        not contain the |center| anchor.
+        
+        It is now the job of the \meta{code} to set up |\pgf@x| and |\pgf@y|
+        such that they specify the point on the shape's border that lies on a
+        straight line from the shape's center to the point $p$. Usually, this is
+        a somewhat complicated computation, involving many case distinctions and
+        some basic math. Note that the output coordinates must be returned in the
+        shape's coordinate system, \emph{no longer} relative to the |center|
+        anchor. While these different points of reference are only noticeable if
+        the |center| anchor is not at the origin of the shape's coordinate system,
+        it implies that ``doing nothing'' as a border anchor, i.e., returning the
+        point that was fed to |\pgfpointshapeborder| requires adding the |center|
+        anchor to the input coordinates.
+
+        For our |simple rectangle| we must compute a point on the border of a
+        rectangle whose one corner is the origin (ignoring the depth for
+        simplicity) and whose other corner is |\upperrightcorner|. The
+        following code might be used:
+        %
+\begin{codeexample}[code only]
+\anchorborder{%
+  % Call a function that computes a border point. Since this
+  % function will modify dimensions like \pgf@x, we must move them to
+  % other dimensions.
+  \@tempdima=\pgf@x
+  \@tempdimb=\pgf@y
+  \pgfpointborderrectangle{\pgfpoint{\@tempdima}{\@tempdimb}}{\upperrightcorner}
+}
+\end{codeexample}
+    \end{command}
+    %
+    \begin{command}{\backgroundpath\marg{code}}
+        This command specifies the path that ``makes up'' the background of the
+        shape. Note that the shape cannot prescribe what is going to happen
+        with the path: It might be drawn, shaded, filled, or even thrown away.
+        If you want to specify that something should ``always'' happen when
+        this shape is drawn (for example, if the shape is a stop-sign, we
+        \emph{always} want it to be filled with a red color), you can use
+        commands like |\beforebackgroundpath|, explained below.
+
+        When the \meta{code} is executed, all saved anchors will be in effect.
+        The \meta{code} should contain path construction commands.
+
+        For our |simple rectangle|, the following code might be used:
+        %
+\begin{codeexample}[code only]
+\backgroundpath{
+  \pgfpathrectanglecorners
+    {\upperrightcorner}
+    {\pgfpointscale{-1}{\upperrightcorner}}
+}
+\end{codeexample}
+        %
+        As the name suggests, the background path is used ``behind'' the text
+        labels. Thus, this path is used first, then the text labels are drawn,
+        possibly obscuring part of the path.
+    \end{command}
+    %
+    \begin{command}{\foregroundpath\marg{code}}
+        This command works like |\backgroundpath|, only it is invoked after the
+        text labels have been drawn. This means that this path can possibly
+        obscure (part of) the text labels.
+    \end{command}
+    %
+    \begin{command}{\behindbackgroundpath\marg{code}}
+        Unlike the previous two commands, \meta{code} should not only construct
+        a path, it should also use this path in whatever way is appropriate.
+        For example, the \meta{code} might fill some area with a uniform color.
+
+        Whatever the \meta{code} does, it does it first. This means that any
+        drawing done by \meta{code} will be even behind the background path.
+
+        Note that the \meta{code} is protected with a |{pgfscope}|.
+    \end{command}
+    %
+    \begin{command}{\beforebackgroundpath\marg{code}}
+        This command works like |\behindbackgroundpath|, only the \meta{code}
+        is executed after the background path has been used, but before the
+        texts label are drawn.
+    \end{command}
+    %
+    \begin{command}{\behindforegroundpath\marg{code}}
+        The \meta{code} is executed after the text labels have been drawn, but
+        before the foreground path is used.
+    \end{command}
+    %
+    \begin{command}{\beforeforegroundpath\marg{code}}
+        This \meta{code} is executed at the very end.
+    \end{command}
+    %
+    \begin{command}{\inheritsavedanchors|[from=|\marg{another shape name}|]|}
+        This command allows you to inherit the code for saved anchors from
+        \meta{another shape name}. The idea is that if you wish to create a new
+        shape that is just a small modification of a another shape, you can
+        recycle the code used for \meta{another shape name}.
+
+        The effect of this command is the same as if you had called
+        |\savedanchor| and |\saveddimen| for each saved anchor or saved
+        dimension declared in \meta{another shape name}. Thus, it is not
+        possible to ``selectively'' inherit only some saved anchors, you always
+        have to inherit all saved anchors from another shape. However, you can
+        inherit the saved anchors of more than one shape by calling this
+        command several times.
+    \end{command}
+    %
+    \begin{command}{\inheritbehindbackgroundpath|[from=|\marg{another shape name}|]|}
+        This command can be used to inherit the code used for the drawings
+        behind the background path from \meta{another shape name}.
+    \end{command}
+    %
+    \begin{command}{\inheritbackgroundpath|[from=|\marg{another shape name}|]|}
+        Inherits the background path code from \meta{another shape name}.
+    \end{command}
+    %
+    \begin{command}{\inheritbeforebackgroundpath|[from=|\marg{another shape name}|]|}
+        Inherits the before background path code from \meta{another shape
+        name}.
+    \end{command}
+    %
+    \begin{command}{\inheritbehindforegroundpath|[from=|\marg{another shape name}|]|}
+        Inherits the behind foreground path code from \meta{another shape
+        name}.
+    \end{command}
+    %
+    \begin{command}{\inheritforegroundpath|[from=|\marg{another shape name}|]|}
+        Inherits the foreground path code from \meta{another shape name}.
+    \end{command}
+    %
+    \begin{command}{\inheritbeforeforegroundpath|[from=|\marg{another shape name}|]|}
+        Inherits the before foreground path code from \meta{another shape
+        name}.
+    \end{command}
+    %
+    \begin{command}{\inheritanchor|[from=|\marg{another shape name}|]|\marg{name}}
+        Inherits the code of one specific anchor named \meta{name} from
+        \meta{another shape name}. Thus, unlike saved anchors, which must be
+        inherited collectively, normal anchors can and must be inherited
+        individually.
+    \end{command}
+    %
+    \begin{command}{\inheritanchorborder|[from=|\marg{another shape name}|]|}
+        Inherits the border anchor code from \meta{another shape name}.
+    \end{command}
+
+    The following example shows how a shape can be defined that relies heavily
+    on inheritance:
+    %
+\makeatletter
+\begin{codeexample}[
+    preamble={\usetikzlibrary{shapes.geometric}},
+    pre={\makeatletter},
+]
+\pgfdeclareshape{document}{
+  \inheritsavedanchors[from=rectangle] % this is nearly a rectangle
+  \inheritanchorborder[from=rectangle]
+  \inheritanchor[from=rectangle]{center}
+  \inheritanchor[from=rectangle]{north}
+  \inheritanchor[from=rectangle]{south}
+  \inheritanchor[from=rectangle]{west}
+  \inheritanchor[from=rectangle]{east}
+  % ... and possibly more
+  \backgroundpath{% this is new
+    % store lower right in xa/ya and upper right in xb/yb
+    \southwest \pgf@xa=\pgf@x \pgf@ya=\pgf@y
+    \northeast \pgf@xb=\pgf@x \pgf@yb=\pgf@y
+    % compute corner of ``flipped page''
+    \pgf@xc=\pgf@xb \advance\pgf@xc by-5pt % this should be a parameter
+    \pgf@yc=\pgf@yb \advance\pgf@yc by-5pt
+    % construct main path
+    \pgfpathmoveto{\pgfpoint{\pgf@xa}{\pgf@ya}}
+    \pgfpathlineto{\pgfpoint{\pgf@xa}{\pgf@yb}}
+    \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yb}}
+    \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}}
+    \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@ya}}
+    \pgfpathclose
+    % add little corner
+    \pgfpathmoveto{\pgfpoint{\pgf@xc}{\pgf@yb}}
+    \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}}
+    \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}}
+    \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}}
+ }
+}\hskip-1.2cm
+\begin{tikzpicture}
+  \node[shade,draw,shape=document,inner sep=2ex] (x) {Remark};
+  \node[fill=yellow!80!black,draw,ellipse,double]
+    at ([shift=(-80:3cm)]x) (y) {Use Case};
+
+  \draw[dashed] (x) -- (y);
+\end{tikzpicture}
+\end{codeexample}
+    %
+\end{command}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual"
+%%% End:
-- 
cgit v1.2.3

