summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex3061
1 files changed, 3061 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex b/graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex
new file mode 100644
index 0000000000..f30010976a
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-tikz-shapes.tex
@@ -0,0 +1,3061 @@
+% 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 Edges}
+\label{section-nodes}
+
+\subsection{Overview}
+
+In the present section, the usage of \emph{nodes} in \tikzname\ is explained. A
+node is typically a rectangle or circle or another simple shape with some text
+on it.
+
+Nodes are added to paths using the special path operation |node|. Nodes
+\emph{are not part of the path itself}. Rather, they are added to the picture
+just before or after the path has been drawn.
+
+In Section~\ref{section-nodes-basic} the basic syntax of the node operation is
+explained, followed in Section~\ref{section-nodes-multi} by the syntax for
+multi-part nodes, which are nodes that contain several different text parts.
+After this, the different options for the text in nodes are explained. In
+Section~\ref{section-nodes-anchors} the concept of \emph{anchors} is introduced
+along with their usage. In Section~\ref{section-nodes-transformations} the
+different ways transformations affect nodes are studied.
+Sections~\ref{section-nodes-placing-1} and~\ref{section-nodes-placing-2} are
+about placing nodes on or next to straight lines and curves.
+Section~\ref{section-nodes-connecting} explains how a node can be used as a
+``pseudo-coordinate''. Section~\ref{section-nodes-edges} introduces the |edge|
+operation, which works similar to the |to| operation and also similar to the
+|node| operation.
+
+
+\subsection{Nodes and Their Shapes}
+\label{section-nodes-basic}
+
+In the simplest case, a node is just some text that is placed at some
+coordinate. However, a node can also have a border drawn around it or have a
+more complex background and foreground. Indeed, some nodes do not have a text
+at all, but consist solely of the background. You can name nodes so that you
+can reference their coordinates later in the same picture or, if certain
+precautions are taken as explained in Section~\ref{section-cross-picture-tikz},
+also in different pictures.
+
+There are no special \TeX\ commands for adding a node to a picture; rather,
+there is path operation called |node| for this. Nodes are created whenever
+\tikzname\ encounters |node| or |coordinate| at a point on a path where it
+would expect a normal path operation (like |-- (1,1)| or |rectangle (1,1)|). It
+is also possible to give node specifications \emph{inside} certain path
+operations as explained later.
+
+The node operation is typically followed by some options, which apply only to
+the node. Then, you can optionally \emph{name} the node by providing a name in
+parentheses. Lastly, for the |node| operation you must provide some label text
+for the node in curly braces, while for the |coordinate| operation you may not.
+The node is placed at the current position of the path either \emph{after the
+path has been drawn} or (more seldomly and only if you add the |behind path|
+option) \emph{just before the path is drawn.} Thus, all nodes are drawn ``on
+top'' or ``behind'' the path and are retained until the path is complete. If
+there are several nodes on a path, perhaps some behind and some on top of the
+path, first come the nodes behind the path in the order they were encountered,
+then comes that path, and then come the remaining node, again in the order they
+are encountered.
+%
+\begin{codeexample}[]
+\tikz \fill [fill=yellow!80!black]
+ (0,0) node {first node}
+ -- (1,1) node[behind path] {second node}
+ -- (2,0) node {third node};
+\end{codeexample}
+
+
+\subsubsection{Syntax of the Node Command}
+
+The syntax for specifying nodes is the following:
+%
+\begin{pathoperation}{node}{
+ \opt{\meta{foreach statements}}
+ \opt{|[|\meta{options}|]|}
+ \opt{|(|\meta{name}|)|}
+ \opt{|at(|\meta{coordinate}|)|}
+ \opt{|:|\meta{animation attribute}|=|\marg{options}}
+ \opt{\marg{node contents}}%
+}
+ Since this path operation is one of the most involved around, let us go
+ over it step by step.
+
+ \medskip
+ \textbf{Order of the parts of the specification.}
+ Everything between ``|node|'' and the opening brace of a node is optional.
+ If there are \meta{foreach statements}, they must come first, directly
+ following ``|node|''. Other than that, the ordering of all the other
+ elements of a node specification (the \meta{options}, the \meta{name},
+ \meta{coordinate}, and \meta{animation attribute}) is arbitrary, indeed,
+ there can be multiple occurrences of any of these elements (although for
+ the name and the coordinate this makes no sense).
+
+ \medskip
+ \textbf{The text of a node.}
+ At the end of a node, you must (normally) provide some \meta{node contents}
+ in curly braces; indeed, the ``end'' of the node specification is detected
+ by the opening curly brace. For normal nodes it is possible to use
+ ``fragile'' stuff inside the \meta{node contents} like the |\verb| command
+ (for the technically savvy: code inside the \meta{node contents} is allowed
+ to change catcodes; however, this rule does not apply to ``nodes on a
+ path'' to be discussed later).
+
+ Instead of giving \meta{node contents} at the end of the node in curly
+ braces, you can also use the following key:
+ %
+ \begin{key}{/tikz/node contents=\meta{node contents}}
+ \label{option-node-contents}%
+ This key sets the contents of the node to the given text as if you had
+ given it at the end in curly braces. When the option is used inside the
+ options of a node, the parsing of the node stops immediately after the
+ end of the option block. In particular, the option block cannot be
+ followed by further option blocks or curly braces (or, rather, these do
+ not count as part of the node specification.) Also note that the
+ \meta{node contents} may not contain fragile stuff since the catcodes
+ get fixed upon reading the options. Here is an example:
+ %
+\begin{codeexample}[]
+\tikz {
+ \path (0,0) node [red] {A}
+ (1,0) node [blue] {B}
+ (2,0) node [green, node contents=C]
+ (3,0) node [node contents=D] ;
+}
+\end{codeexample}
+ %
+\end{key}
+
+ \medskip
+ \textbf{Specifying the location of the node.}
+ Nodes are placed at the last position mentioned on the path. The effect of
+ adding ``|at|'' to a node specification is that the coordinate given after
+ |at| is used instead. The |at| syntax is not available when a node is given
+ inside a path operation (it would not make any sense there).
+
+ \begin{key}{/tikz/at=\meta{coordinate}}
+ This is another way of specifying the |at| coordinate. Note that,
+ typically, you will have to enclose the \meta{coordinate} in curly
+ braces so that a comma inside the \meta{coordinate} does not confuse
+ \TeX.
+ \end{key}
+
+ Another aspect of the ``location'' of a node is whether it appears \emph{in
+ front of} or \emph{behind} the current path. You can change which of these
+ two possibilities happens on a node-by-node basis using the following keys:
+ %
+ \begin{key}{/tikz/behind path}
+ When this key is set, either as a local option for the node or some
+ surrounding scope, the node will be drawn behind the current path. For
+ this, \tikzname\ collects all nodes defined on the current path with
+ this option set and then inserts all of them, in the order they appear,
+ just before it draws the path. Thus, several nodes with this option set
+ may obscure one another, but never the path itself. ``Just before it
+ draws the path'' actually means that the nodes are inserted into the
+ page output just before any pre-actions are applied to the path (see
+ below for what pre-actions are).
+ %
+\begin{codeexample}[]
+\tikz \fill [fill=blue!50, draw=blue, very thick]
+ (0,0) node [behind path, fill=red!50] {first node}
+ -- (1.5,0) node [behind path, fill=green!50] {second node}
+ -- (1.5,1) node [behind path, fill=brown!50] {third node}
+ -- (0,1) node [ fill=blue!30] {fourth node};
+\end{codeexample}
+
+ Note that |behind path| only applies to the current path; not to the
+ current scope or picture. To put a node ``behind everything'' you need
+ to use layers and options like |on background layer|, see the
+ |backgrounds| library in Section~\ref{section-tikz-backgrounds}.
+ \end{key}
+
+ \begin{key}{/tikz/in front of path}
+ This is the opposite of |behind path|: It causes nodes to be drawn on
+ top of the path. Since this is the default behavior, you usually do
+ not need this option; it is only needed when an enclosing scope has
+ used |behind path| and you now wish to ``switch back'' to the normal
+ behavior.
+ \end{key}
+
+ \medskip
+ \textbf{The name of a node.}
+ The |(|\meta{name}|)| is a name for later reference and it is optional. You
+ may also add the option |name=|\meta{name} to the \meta{option} list; it
+ has the same effect.
+
+ \begin{key}{/tikz/name=\meta{node name}}
+ Assigns a name to the node for later reference. Since this is a
+ ``high-level'' name (drivers never know of it), you can use spaces,
+ number, letters, or whatever you like when naming a node. Thus, you can
+ name a node just |1| or perhaps |start of chart| or even |y_1|. Your
+ node name should \emph{not} contain any punctuation like a dot, a
+ comma, or a colon since these are used to detect what kind of
+ coordinate you mean when you reference a node.
+ \end{key}
+
+ \begin{key}{/tikz/alias=\meta{another node name}}
+ This option allows you to provide another name for the node. Giving
+ this option multiple times will allow you to access the node via
+ several aliases. Using the |node also| syntax, you can also assign an
+ alias name to a node at a later point, see
+ Section~\ref{section-node-also}.
+ \end{key}
+
+ \medskip
+ \textbf{The options of a node.}
+ The \meta{options} is an optional list of options that \emph{apply only to
+ the node} and have no effect outside. The other way round, most ``outside''
+ options also apply to the node, but not all. For example, the ``outside''
+ rotation does not apply to nodes (unless some special options are used,
+ sigh). Also, the outside path action, like |draw| or |fill|, never applies
+ to the node and must be given in the node (unless some special other
+ options are used, deep sigh).
+
+ \medskip
+ \textbf{The shape of a node.}
+ As mentioned before, we can add a border and even a background to a node:
+ %
+\begin{codeexample}[]
+\tikz \fill[fill=yellow!80!black]
+ (0,0) node {first node}
+ -- (1,1) node[draw, behind path] {second node}
+ -- (0,2) node[fill=red!20,draw,double,rounded corners] {third node};
+\end{codeexample}
+
+ The ``border'' is actually just a special case of a much more general
+ mechanism. Each node has a certain \emph{shape} which, by default, is a
+ rectangle. However, we can also ask \tikzname\ to use a circle shape
+ instead or an ellipse shape (you have to include one of the
+ |shapes.geometric| library for the latter shape):
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
+\tikz \fill[fill=yellow!80!black]
+ (0,0) node {first node}
+ -- (1,1) node[ellipse,draw, behind path] {second node}
+ -- (0,2) node[circle,fill=red!20] {third node};
+\end{codeexample}
+
+ There are many more shapes available such as, say, a shape for a resistor
+ or a large arrow, see the |shapes| library in
+ Section~\ref{section-libs-shapes} for details.
+
+ To select the shape of a node, the following option is used:
+ %
+ \begin{key}{/tikz/shape=\meta{shape name} (initially rectangle)}
+ Select the shape either of the current node or, when this option is not
+ given inside a node but somewhere outside, the shape of all nodes in
+ the current scope.%
+ \indexoption{\meta{shape name}}
+
+ Since this option is used often, you can leave out the |shape=|. When
+ \tikzname\ encounters an option like |circle| that it does not know, it
+ will, after everything else has failed, check whether this option is
+ the name of some shape. If so, that shape is selected as if you had
+ said |shape=|\meta{shape name}.
+
+ By default, the following shapes are available: |rectangle|, |circle|,
+ |coordinate|. Details of these shapes, like their anchors and size
+ options, are discussed in Section~\ref{section-the-shapes}.
+ \end{key}
+
+ \medskip
+ \textbf{Animating a node.}
+ When you say |:|\meta{animation attribute}|={|\meta{options}|}|, an
+ \emph{animation} of the specified attribute is added to the node.
+ Animations are discussed in detail in
+ Section~\ref{section-tikz-animations}. Here is a typical example of how
+ this syntax can be used:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{animations}},animation list={0.5,1,1.5,2}]
+\tikz
+ \node :fill opacity = { 0s="1", 2s="0", begin on=click }
+ :rotate = { 0s="0", 2s="90", begin on=click }
+ [fill = blue!20, draw = blue, ultra thick, circle]
+ {Click me!};
+\end{codeexample}
+
+ \medskip
+ \textbf{The foreach statement for nodes.}
+ At the beginning of a node specification (and only there) you can provide
+ multiple \meta{foreach statements}, each of which has the form |foreach|
+ \meta{var} |in| \meta{list} (note that there is no backslash before
+ |foreach|). When they are given, instead of a single node, multiple nodes
+ will be created: The \meta{var} will iterate over all values of \meta{list}
+ and for each of them, a new node is created. These nodes are all created
+ using all the text following the \meta{foreach statements}, but in each
+ copy the \meta{var} will have the current value of the current element in
+ the \meta{list}.
+
+ As an example, the following two codes have the same effect:
+ %
+\begin{codeexample}[]
+\tikz \draw (0,0) node foreach \x in {1,2,3} at (\x,0) {\x};
+\end{codeexample}
+\begin{codeexample}[]
+\tikz \draw (0,0) node at (1,0) {1} node at (2,0) {2} node at (3,0) {3};
+\end{codeexample}
+%
+ When you provide several |foreach| statements, they work like ``nested
+ loops'':
+ %
+\begin{codeexample}[]
+\tikz \node foreach \x in {1,...,4} foreach \y in {1,2,3}
+ [draw] at (\x,\y) {\x,\y};
+\end{codeexample}
+ %
+ As the example shows, a \meta{list} can contain ellipses (three dots) to
+ indicate that a larger number of numbers is meant. Indeed, you can use the
+ full power of the |\foreach| command here, including multiple parameters
+ and options, see Section~\ref{section-foreach}.
+
+ \medskip
+ \textbf{Styles for nodes.}
+ The following styles influence how nodes are rendered:
+ %
+ \begin{stylekey}{/tikz/every node (initially \normalfont empty)}
+ This style is installed at the beginning of every node.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}[every node/.style={draw}]
+ \draw (0,0) node {A} -- (1,1) node {B};
+\end{tikzpicture}
+\end{codeexample}
+ \end{stylekey}
+ %
+ \begin{stylekey}{/tikz/every \meta{shape} node (initially \normalfont empty)}
+ These styles are installed at the beginning of a node of a given
+ \meta{shape}. For example, |every rectangle node| is used for rectangle
+ nodes, and so on.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ [every rectangle node/.style={draw},
+ every circle node/.style={draw,double}]
+ \draw (0,0) node[rectangle] {A} -- (1,1) node[circle] {B};
+\end{tikzpicture}
+\end{codeexample}
+ \end{stylekey}
+
+ \begin{key}{/tikz/execute at begin node=\meta{code}}
+ This option causes \meta{code} to be executed at the beginning of a
+ node. Using this option multiple times will cause the code to
+ accumulate.
+ \end{key}
+
+ \begin{key}{/tikz/execute at end node=\meta{code}}
+ This option installs \meta{code} that will be executed at the end of
+ the node. Using this option multiple times will cause the code to
+ accumulate.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ [execute at begin node={A},
+ execute at end node={D}]
+ \node[execute at begin node={B}] {C};
+\end{tikzpicture}
+\end{codeexample}
+ %
+ \end{key}
+
+ \medskip
+ \textbf{Name scopes.}
+ It turns out that the name of a node can further be influenced using two
+ keys:
+ %
+ \begin{key}{/tikz/name prefix=\meta{text} (initially \normalfont empty)}
+ The value of this key is prefixed to every node inside the current
+ scope. This includes both the naming of the node (via the |name| key or
+ via the implicit |(|\meta{name}|)| syntax) as well as any referencing
+ of the node. Outside the scope, the nodes can (and need to) be
+ referenced using ``full name'' consisting of the prefix and the node
+ name.
+
+ The net effect of this is that you can set the name prefix at the
+ beginning of a scope to some value and then use short and simple names
+ for the nodes inside the scope. Later, outside the scope, you can
+ reference the nodes via their full name:
+ %
+\begin{codeexample}[]
+\tikz {
+ \begin{scope}[name prefix = top-]
+ \node (A) at (0,1) {A};
+ \node (B) at (1,1) {B};
+ \draw (A) -- (B);
+ \end{scope}
+ \begin{scope}[name prefix = bottom-]
+ \node (A) at (0,0) {A};
+ \node (B) at (1,0) {B};
+ \draw (A) -- (B);
+ \end{scope}
+
+ \draw [red] (top-A) -- (bottom-B);
+}
+\end{codeexample}
+ %
+ As can be seen, name prefixing makes it easy to write reusable code.
+ \end{key}
+ %
+ \begin{key}{/tikz/name suffix=\meta{text} (initially \normalfont empty)}
+ Works as |name prefix|, only the \meta{text} is appended to every node
+ name in the current scope.
+ \end{key}
+\end{pathoperation}
+
+There is a special syntax for specifying ``light-weight'' nodes:
+
+\begin{pathoperation}{coordinate}{\opt{|[|\meta{options}|]|}|(|\meta{name}|)|\opt{|at(|\meta{coordinate}|)|}}
+ This has the same effect as
+
+ |\node[shape=coordinate]|\verb|[|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|,
+
+ where the |at| part may be omitted.
+\end{pathoperation}
+
+Since nodes are often the only path operation on paths, there are two special
+commands for creating paths containing only a node:
+
+\begin{command}{\node}
+ Inside |{tikzpicture}| this is an abbreviation for |\path node|.
+\end{command}
+
+\begin{command}{\coordinate}
+ Inside |{tikzpicture}| this is an abbreviation for |\path coordinate|.
+\end{command}
+
+
+\subsubsection{Predefined Shapes}
+\label{section-nodes-predefined}
+\label{section-the-shapes}
+
+\pgfname\ \todosp{why two labels for the same point? The first doesn't seem to
+be used anywhere} and \tikzname\ define three shapes, by default:
+%
+\begin{itemize}
+ \item |rectangle|,
+ \item |circle|, and
+ \item |coordinate|.
+\end{itemize}
+%
+By loading library packages, you can define more shapes like ellipses or
+diamonds; see Section~\ref{section-libs-shapes} for the complete list of
+shapes.
+
+\label{section-tikz-coordinate-shape}%
+The |coordinate| shape is handled in a special way by \tikzname. When a node
+|x| whose shape is |coordinate| is used as a coordinate |(x)|, this has the
+same effect as if you had said |(x.center)|. None of the special ``line
+shortening rules'' apply in this case. This can be useful since, normally, the
+line shortening causes paths to be segmented and they cannot be used for
+filling. Here is an example that demonstrates the difference:
+%
+\begin{codeexample}[]
+\begin{tikzpicture}[every node/.style={draw}]
+ \path[yshift=1.5cm,shape=rectangle]
+ (0,0) node(a1){} (1,0) node(a2){}
+ (1,1) node(a3){} (0,1) node(a4){};
+ \filldraw[fill=yellow!80!black] (a1) -- (a2) -- (a3) -- (a4);
+
+ \path[shape=coordinate]
+ (0,0) coordinate(b1) (1,0) coordinate(b2)
+ (1,1) coordinate(b3) (0,1) coordinate(b4);
+ \filldraw[fill=yellow!80!black] (b1) -- (b2) -- (b3) -- (b4);
+\end{tikzpicture}
+\end{codeexample}
+
+
+\subsubsection{Common Options: Separations, Margins, Padding and
+ Border Rotation}
+\label{section-shape-seps}
+\label{section-shape-common-options}
+
+The \todosp{why two labels for the same point?} exact behavior of shapes
+differs, shapes defined for more special purposes (like a, say, transistor
+shape) will have even more custom behaviors. However, there are some options
+that apply to most shapes:
+
+\begin{key}{/pgf/inner sep=\meta{dimension} (initially .3333em)}
+ \keyalias{tikz}
+ An additional (invisible) separation space of \meta{dimension} will be
+ added inside the shape, between the text and the shape's background path.
+ The effect is as if you had added appropriate horizontal and vertical skips
+ at the beginning and end of the text to make it a bit ``larger''.
+
+ For those familiar with \textsc{css}, this is the same as \emph{padding}.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw (0,0) node[inner sep=0pt,draw] {tight}
+ (0cm,2em) node[inner sep=5pt,draw] {loose}
+ (0cm,4em) node[fill=yellow!80!black] {default};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/inner xsep=\meta{dimension} (initially .3333em)}
+ \keyalias{tikz}
+ Specifies the inner separation in the $x$-direction, only.
+\end{key}
+
+\begin{key}{/pgf/inner ysep=\meta{dimension} (initially .3333em)}
+ \keyalias{tikz}
+ Specifies the inner separation in the $y$-direction, only.
+\end{key}
+
+\begin{key}{/pgf/outer sep=\meta{dimension or ``auto''}}
+ \keyalias{tikz}
+ This option adds an additional (invisible) separation space of
+ \meta{dimension} outside the background path. The main effect of this
+ option is that all anchors will move a little ``to the outside''.
+
+ For those familiar with \textsc{css}, this is same as \emph{margin}.
+
+ The default for this option is half the line width. When the default is
+ used and when the background path is draw, the anchors will lie exactly on
+ the ``outside border'' of the path (not on the path itself).
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[line width=5pt]
+ (0,0) node[fill=yellow!80!black] (f) {filled}
+ (2,0) node[draw] (d) {drawn}
+ (1,-2) node[draw,scale=2] (s) {scaled};
+
+ \draw[->] (1,-1) -- (f);
+ \draw[->] (1,-1) -- (d);
+ \draw[->] (1,-1) -- (s);
+\end{tikzpicture}
+\end{codeexample}
+
+ As the above example demonstrates, the standard settings for the outer sep
+ are not always ``correct''. First, when a shape is filled, but not drawn,
+ the outer sep should actually be |0|. Second, when a node is scaled, for
+ instance by a factor of 5, the outer separation also gets scaled by a
+ factor of 5, while the line width stays at its original width; again
+ causing problems.
+
+ In such cases, you can say |outer sep=auto| to make \tikzname\ \emph{try}
+ to compensate for the effects described above. This is done by, firstly,
+ setting the outer sep to |0| when no drawing is done and, secondly, setting
+ the outer separations to half the line width (as before) times two
+ adjustment factors, one for the horizontal separations and one for the
+ vertical separations (see Section~\ref{section-adjustment-transformations}
+ for details on these factors). Note, however, that these factors can
+ compensate only for transformations that are either scalings plus rotations
+ or scalings with different magnitudes in the horizontal and the vertical
+ direction. If you apply slanting, the factors will only approximate the
+ correct values.
+
+ In general, it is a good idea to say |outer sep=auto| at some early stage.
+ It is not the default mainly for compatibility with earlier versions.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}[outer sep=auto]
+ \draw[line width=5pt]
+ (0,0) node[fill=yellow!80!black] (f) {filled}
+ (2,0) node[draw] (d) {drawn}
+ (1,-2) node[draw,scale=2] (s) {scaled};
+
+ \draw[->] (1,-1) -- (f);
+ \draw[->] (1,-1) -- (d);
+ \draw[->] (1,-1) -- (s);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/outer xsep=\meta{dimension} (initially .5\string\pgflinewidth)}
+ \keyalias{tikz}
+ Specifies the outer separation in the $x$-direction, only. This value will
+ be overwritten when |outer sep| is set, either to the value given there or
+ a computed value in case of |auto|.
+\end{key}
+
+\begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)}
+ \keyalias{tikz}
+ Specifies the outer separation in the $y$-direction, only.
+\end{key}
+
+\begin{key}{/pgf/minimum height=\meta{dimension} (initially 1pt)}
+ \keyalias{tikz}
+ This option ensures that the height of the shape (including the inner, but
+ ignoring the outer separation) will be at least \meta{dimension}. Thus, if
+ the text plus the inner separation is not at least as large as
+ \meta{dimension}, the shape will be enlarged appropriately. However, if the
+ text is already larger than \meta{dimension}, the shape will not be shrunk.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw (0,0) node[minimum height=1cm,draw] {1cm}
+ (2,0) node[minimum height=0cm,draw] {0cm};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/minimum width=\meta{dimension} (initially 1pt)}
+ \keyalias{tikz}
+ Same as |minimum height|, only for the width.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw (0,0) node[minimum height=2cm,minimum width=3cm,draw] {$3 \times 2$};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/minimum size=\meta{dimension}}
+ \keyalias{tikz}
+ Sets both the minimum height and width at the same time.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw (0,0) node[minimum size=2cm,draw] {square};
+ \draw (0,-2) node[minimum size=2cm,draw,circle] {circle};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/shape aspect=\meta{aspect ratio}}
+ \keyalias{tikz}
+ Sets a desired aspect ratio for the shape. For the |diamond| shape, this
+ option sets the ratio between width and height of the shape.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
+\begin{tikzpicture}
+ \draw (0,0) node[shape aspect=1,diamond,draw] {aspect 1};
+ \draw (0,-2) node[shape aspect=2,diamond,draw] {aspect 2};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+ \label{section-rotating-shape-borders}
+
+Some shapes (but not all), support a special kind of rotation. This rotation
+affects only the border of a shape and is independent of the node contents, but
+\emph{in addition} to any other transformations.
+%
+\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
+\tikzset{every node/.style={dart, shape border uses incircle,
+ inner sep=1pt, draw}}
+\tikz \node foreach \a/\b/\c in {A/0/0, B/45/0, C/0/45, D/45/45}
+ [shape border rotate=\b, rotate=\c] at (\b/36,-\c/36) {\a};
+\end{codeexample}
+
+There are two types of rotation: restricted and unrestricted. Which type of
+rotation is applied is determined by on how the shape border is constructed. If
+the shape border is constructed using an incircle, that is, a circle that
+tightly fits the node contents (including the |inner sep|), then the rotation
+can be unrestricted. If, however, the border is constructed using the natural
+dimensions of the node contents, the rotation is restricted to integer
+multiples of 90 degrees.
+
+Why should there be two kinds of rotation and border construction? Borders
+constructed using the natural dimensions of the node contents provide a much
+tighter fit to the node contents, but to maintain this tight fit, the border
+rotation must be restricted to integer multiples of 90 degrees. By using an
+incircle, unrestricted rotation is possible, but the border will not make a
+very tight fit to the node contents.
+%
+\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
+\tikzset{every node/.style={isosceles triangle, draw}}
+\begin{tikzpicture}
+ \node {abc};
+ \node [shape border uses incircle] at (2,0) {abc};
+\end{tikzpicture}
+\end{codeexample}
+
+There are \pgfname{} keys that determine how a shape border is constructed, and
+to specify its rotation. It should be noted that not all shapes support these
+keys, so reference should be made to the documentation for individual shapes.
+
+\begin{key}{/pgf/shape border uses incircle=\opt{\meta{boolean}} (default true)}
+ \keyalias{tikz}
+ Determines if the border of a shape is constructed using the incircle. If
+ no value is given \meta{boolean} will take the default value |true|.
+\end{key}
+
+\begin{key}{/pgf/shape border rotate=\meta{angle} (initially 0)}
+ \keyalias{tikz}
+ Rotates the border of a shape independently of the node contents, but in
+ addition to any other transformations. If the shape border is not
+ constructed using the incircle, the rotation will be rounded to the nearest
+ integer multiple of 90 degrees when the shape is drawn.
+\end{key}
+
+Note that if the border of the shape is rotated, the compass point anchors, and
+`text box' anchors (including |mid east|, |base west|, and so on), \emph{do not
+rotate}, but the other anchors do:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
+\tikzset{every node/.style={shape=trapezium, draw, shape border uses incircle}}
+\begin{tikzpicture}
+ \node at (0,0) (A) {A};
+ \node [shape border rotate=30] at (1.5,0) (B) {B};
+ \foreach \s/\t in
+ {left side/base east, bottom side/north, bottom left corner/base}{
+ \fill[red] (A.\s) circle(1.5pt) (B.\s) circle(1.5pt);
+ \fill[blue] (A.\t) circle(1.5pt) (B.\t) circle(1.5pt);
+ }
+\end{tikzpicture}
+\end{codeexample}
+
+Finally, a somewhat unfortunate side-effect of rotating shape borders is that
+the supporting shapes do not distinguish between |outer xsep| and |outer ysep|,
+and typically, the larger of the two values will be used.
+
+
+\subsection{Multi-Part Nodes}
+\label{section-nodes-multi}
+
+Most nodes just have a single simple text label. However, nodes of a more
+complicated shape might be made up from several \emph{node parts}. For example,
+in automata theory a so-called Moore state has a state name, drawn in the upper
+part of the state circle, and an output text, drawn in the lower part of the
+state circle. These two parts are quite independent. Similarly, a \textsc{uml}
+class shape would have a name part, a method part, and an attributes part.
+Different molecule shapes might use parts for the different atoms to be drawn
+at the different positions, and so on.
+
+Both \pgfname\ and \tikzname\ support such multipart nodes. On the lower level,
+\pgfname\ provides a system for specifying that a shape consists of several
+parts. On the \tikzname\ level, you specify the different node parts by using
+the following command:
+
+\begin{command}{\nodepart\opt{|[|\meta{options}|]|}\marg{part name}}
+ This command can only be used inside the \meta{text} argument of a |node|
+ path operation. It works a little bit like a |\part| command in \LaTeX. It
+ will stop the typesetting of whatever node part was typeset until now and
+ then start putting all following text into the node part named \meta{part
+ name} -- until another |\nodepart| is encountered or until the node
+ \meta{text} ends. The \meta{options} will be local to this part.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
+\begin{tikzpicture}
+ \node [circle split,draw,double,fill=red!20]
+ {
+ % No \nodepart has been used, yet. So, the following is put in the
+ % ``text'' node part by default.
+ $q_1$
+ \nodepart{lower} % Ok, end ``text'' part, start ``output'' part
+ $00$
+ }; % output part ended.
+\end{tikzpicture}
+\end{codeexample}
+
+ You will have to lookup which parts are defined by a shape.
+
+ The following styles influences node parts:
+ %
+ \begin{stylekey}{/tikz/every \meta{part name} node part (initially \normalfont empty)}
+ This style is installed at the beginning of every node part named
+ \meta{part name}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
+\tikz [every lower node part/.style={red}]
+ \node [circle split,draw] {$q_1$ \nodepart{lower} $00$};
+\end{codeexample}
+ \end{stylekey}
+\end{command}
+
+
+\subsection{The Node Text}
+\label{section-nodes-options}
+
+\subsubsection{Text Parameters: Color and Opacity}
+
+The simplest option for the text in nodes is its color. Normally, this color is
+just the last color installed using |color=|, possibly inherited from another
+scope. However, it is possible to specifically set the color used for text
+using the following option:
+
+\begin{key}{/tikz/text=\meta{color}}
+ Sets the color to be used for text labels. A |color=| option will
+ immediately override this option.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[red] (0,0) -- +(1,1) node[above] {red};
+ \draw[text=red] (1,0) -- +(1,1) node[above] {red};
+ \draw (2,0) -- +(1,1) node[above,red] {red};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+Just like the color itself, you may also wish to set the opacity of the text
+only. For this, use the |text opacity| option, which is detailed in
+Section~\ref{section-tikz-transparency}.
+
+
+\subsubsection{Text Parameters: Font}
+
+Next, you may wish to adjust the font used for the text. Naturally, you can
+just use a font command like |\small| or |\rm| at the beginning of a node.
+However, the following two options make it easier to set the font used in nodes
+on a general basis. Let us start with:
+
+\begin{key}{/tikz/node font=\meta{font commands}}
+ This option sets the font used for all text used in a node.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[node font=\itshape] (1,0) -- +(1,1) node[above] {italic};
+\end{tikzpicture}
+\end{codeexample}
+ %
+ Since the \meta{font commands} are executed at a very early stage in the
+ construction of the node, the font selected using this command will also
+ dictate the values of dimensions defined in terms of |em| or |ex|. For
+ instance, when the |minimum height| of a node is |3em|, the actual height
+ will be (at least) three times the line distance selected by the \meta{font
+ commands}:
+\begin{codeexample}[]
+\tikz \node [node font=\tiny, minimum height=3em, draw] {tiny};
+\tikz \node [node font=\small, minimum height=3em, draw] {small};
+\end{codeexample}
+ %
+\end{key}
+
+The other font command is:
+%
+\begin{key}{/tikz/font=\meta{font commands}}
+ Sets the font used for the text inside nodes. However, this font will
+ \emph{not} (yet) be installed when any of the dimensions of the node are
+ being computed, so dimensions like |1em| will be with respect to the font
+ used outside the node (usually the font that was in force when the picture
+ started).
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node [font=\itshape] {italic};
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\tikz \node [font=\tiny, minimum height=3em, draw] {tiny};
+\tikz \node [font=\small, minimum height=3em, draw] {small};
+\end{codeexample}
+
+ A useful example of how the |font| option can be used is the following:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
+\tikz [every text node part/.style={font=\itshape},
+ every lower node part/.style={font=\footnotesize}]
+ \node [circle split,draw] {state \nodepart{lower} output};
+\end{codeexample}
+
+ As can be seen, the font can be changed for each node part. This does
+ \emph{not} work with the |node font| command since, as the name suggests,
+ this command can only be used to select the ``overall'' font for the node
+ and this is done very early.
+\end{key}
+
+
+\subsubsection{Text Parameters: Alignment and Width for Multi-Line Text}
+
+Normally, when a node is typeset, all the text you give in the braces is put in
+one long line (in an |\hbox|, to be precise) and the node will become as wide
+as necessary.
+
+From time to time you may wish to create nodes that contain multiple lines of
+text. There are three different ways of achieving this:
+%
+\begin{enumerate}
+ \item Inside the node, you can put some standard environment that produces
+ multi-line, aligned text. For instance, you can use a |{tabular}|
+ inside a node:
+ %
+\begin{codeexample}[width=5cm]
+\tikz \node [draw] {
+ \begin{tabular}{cc}
+ upper left & upper right\\
+ lower left & lower right
+ \end{tabular}
+};
+\end{codeexample}
+ %
+ This approach offers the most flexibility in the sense that it allows
+ you to use all of the alignment commands offered by your format of
+ choice.
+ \item You use |\\| inside your node to mark the end of lines and then
+ request \tikzname\ to arrange these lines in some manner. This will
+ only be done, however, if the |align| option has been given.
+ %
+\begin{codeexample}[]
+\tikz[align=left] \node[draw] {This is a\\demonstration.};
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\tikz[align=center] \node[draw] {This is a\\demonstration.};
+\end{codeexample}
+ %
+ The |\\| command takes an optional extra space as an argument in square
+ brackets.
+ %
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,align=right]
+ {This is a\\[-2pt] demonstration text for\\[1ex] alignments.};
+\end{codeexample}
+ %
+ \item You can request that \tikzname\ does an automatic line-breaking for
+ you inside the node by specifying a fixed |text width| for the node. In
+ this case, you can still use |\\| to enforce a line-break. Note that
+ when you specify a text width, the node will have this width,
+ independently of whether the text actually ``reaches the end'' of the
+ node.
+\end{enumerate}
+
+Let us now first have a look at the |text width| command.
+ %
+\begin{key}{/tikz/text width=\meta{dimension}}
+ This option will put the text of a node in a box of the given width
+ (something akin to a |{minipage}| of this width, only portable across
+ formats). If the node text is not as wide as \meta{dimension}, it will
+ nevertheless be put in a box of this width. If it is larger, line breaking
+ will be done.
+
+ By default, when this option is given, a ragged right border will be used
+ (|align=left|). This is sensible since, typically, these boxes are narrow
+ and justifying the text looks ugly. You can, however, change the alignment
+ using |align| or directly using commands line |\centering|.
+ %
+\begin{codeexample}[]
+\tikz \draw (0,0) node[fill=yellow!80!black,text width=3cm]
+ {This is a demonstration text for showing how line breaking works.};
+\end{codeexample}
+ %
+ Setting \meta{dimension} to an empty string causes the automatic line
+ breaking to be disabled.
+\end{key}
+
+\begin{key}{/tikz/align=\meta{alignment option}}
+ This key is used to set up an alignment for multi-line text inside a node.
+ If |text width| is set to some width (let us call this \emph{alignment with
+ line breaking}), the |align| key will setup the |\leftskip| and the
+ |\rightskip| in such a way that the text is broken and aligned according to
+ \meta{alignment option}. If |text width| is not set (that is, set to the
+ empty string; let us call this \emph{alignment without line breaking}),
+ then a different mechanism is used internally, namely the key
+ |node halign header|, is set to an appropriate value. While this key, which
+ is documented below, is not to be used by beginners, the net effect is
+ simple: When |text width| is not set, you can use |\\| to break lines and
+ align them according to \meta{alignment option} and the resulting node's
+ width will be minimal to encompass the resulting lines.
+
+ In detail, you can set \meta{alignment option} to one of the following values:
+ %
+ \begin{description}
+ \item[|align=|\declare{|left|}] For alignment without line breaking,
+ the different lines are simply aligned such that their left borders
+ are below one another.
+ %
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,align=left]
+ {This is a\\ demonstration text for\\ alignments.};
+\end{codeexample}
+ %
+ For alignment with line breaking, the same will happen; only the
+ lines will now, additionally, be broken automatically:
+ %
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,text width=3cm,align=left]
+ {This is a demonstration text for showing how line breaking works.};
+\end{codeexample}
+ %
+ \item[|align=|\declare{\texttt{flush left}}] For alignment without line
+ breaking this option has exactly the same effect as |left|.
+ However, for alignment with line breaking, there is a difference:
+ While |left| uses the original plain \TeX\ definition of a ragged
+ right border, in which \TeX\ will try to balance the right border
+ as well as possible, |flush left| causes the right border to be
+ ragged in the \LaTeX-style, in which no balancing occurs. This
+ looks ugly, but it may be useful for very narrow boxes and when you
+ wish to avoid hyphenations.
+ %
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,text width=3cm,align=flush left]
+ {This is a demonstration text for showing how line breaking works.};
+\end{codeexample}
+ %
+ \item[|align=|\declare{|right|}] Works like |left|, only for right
+ alignment.
+ %
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,align=right]
+ {This is a\\ demonstration text for\\ alignments.};
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,text width=3cm,align=right]
+ {This is a demonstration text for showing how line breaking works.};
+\end{codeexample}
+ %
+ \item[|align=|\declare{\texttt{flush right}}] Works like |flush left|,
+ only for right alignment.
+ %
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,text width=3cm,align=flush right]
+ {This is a demonstration text for showing how line breaking works.};
+\end{codeexample}
+ %
+ \item[|align=|\declare{|center|}] Works like |left| or |right|, only
+ for centered alignment.
+ %
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,align=center]
+ {This is a\\ demonstration text for\\ alignments.};
+\end{codeexample}
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,text width=3cm,align=center]
+ {This is a demonstration text for showing how line breaking works.};
+\end{codeexample}
+
+ There is one annoying problem with the |center| alignment (but not
+ with |flush center| and the other options): If you specify a large
+ line width and the node text fits on a single line and is, in fact,
+ much shorter than the specified |text width|, an underfull
+ horizontal box will result. Unfortunately, this cannot be avoided,
+ due to the way \TeX\ works (more precisely, I have thought long and
+ hard about this and have not been able to figure out a sensible way
+ to avoid this). For this reason, \tikzname\ switches off horizontal
+ badness warnings inside boxes with |align=center|. Since this will
+ also suppress some ``wanted'' warnings, there is also an option for
+ switching the warnings on once more:
+ %
+ \begin{key}{/tikz/badness warnings for centered text=\meta{true or false} (initially false)}
+ If set to true, normal badness warnings will be issued for
+ centered boxes. Note that you may get annoying warnings for
+ perfectly normal boxes, namely whenever the box is very large
+ and the contents is not long enough to fill the box
+ sufficiently.
+ \end{key}
+ \item[|align=|\declare{\texttt{flush center}}] Works like |flush left|
+ or |flush right|, only for center alignment. Because of all the
+ trouble that results from the |center| option in conjunction with
+ narrow lines, I suggest picking this option rather than |center|
+ \emph{unless} you have longer text, in which case |center| will
+ give the typographically better results.
+ %
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,text width=3cm,align=flush center]
+ {This is a demonstration text for showing how line breaking works.};
+\end{codeexample}
+ %
+ \item[|align=|\declare{|justify|}] For alignment without line breaking,
+ this has the same effect as |left|. For alignment with line
+ breaking, this causes the text to be ``justified''. Use this only
+ with rather broad nodes.
+{%
+\hbadness=10000
+\begin{codeexample}[]
+\tikz \node[fill=yellow!80!black,text width=3cm,align=justify]
+ {This is a demonstration text for showing how line breaking works.};
+\end{codeexample}
+}
+ In the above example, \TeX\ complains (rightfully) about three very
+ badly typeset lines. (For this manual I asked \TeX\ to stop
+ complaining by using |\hbadness=10000|, but this is a foul deed,
+ indeed.)
+ \item[|align=|\declare{|none|}] Disables all alignments and |\\| will
+ not be redefined.
+ \end{description}
+\end{key}
+
+\begin{key}{/tikz/node halign header=\meta{macro storing a header} (initially \normalfont empty)}
+ This is the key that is used by |align| internally for alignment without
+ line breaking. Read the following only if you are familiar with the
+ |\halign| command.
+
+ This key only has an effect if |text width| is empty, otherwise it is
+ ignored. Furthermore, if \meta{macro storing a header} is empty, then this
+ key also has no effect. So, suppose |text width| is empty, but
+ \meta{header} is not. In this case the following happens:
+
+ When the node text is parsed, the command |\\| is redefined internally.
+ This redefinition is done in such a way that the text from the start of the
+ node to the first occurrence of |\\| is put in an |\hbox|. Then the text
+ following |\\| up to the next |\\| is put in another |\hbox|. This goes on
+ until the text between the last |\\| and the closing |}| is also put in an
+ |\hbox|.
+
+ The \meta{macro storing a header} should be a macro that contains some text
+ suitable for use as a header for the |\halign| command. For instance, you
+ might define
+ %
+\begin{codeexample}[code only]
+\def\myheader{\hfil\hfil##\hfil\cr}
+\tikz [node halign header=\myheader] ...
+\end{codeexample}
+ %
+ You cannot just say |node halign header=\hfil\hfil#\hfil\cr| because this
+ confuses \TeX\ inside matrices, so this detour via a macro is needed.
+
+ Next, conceptually, all these boxes are recursively put inside an |\halign|
+ command. Assuming that \meta{first} is the first of the above boxes, the
+ command |\halign{|\meta{header} |\box|\meta{first} |\cr}| is used to create
+ a new box, which we will call the \meta{previous box}. Then, the following
+ box is created, where \meta{second} is the second input box:
+ |\halign{|\meta{header} |\box|\meta{previous box} |\cr|
+ |\box|\meta{second}|\cr}|. Let us call the resulting box the \meta{previous
+ box} once more. Then the next box that is created is
+ |\halign{|\meta{header} |\box|\meta{previous box} |\cr|
+ |\box|\meta{third}|\cr}|.
+
+ All of this means that if \meta{header} is an |\halign| header like
+ |\hfil#\hfil\cr|, then all boxes will be centered relative to one another.
+ Similarly, a \meta{header} of |\hfil#\cr| causes the text to be flushed
+ right.
+
+ Note that this mechanism is not flexible enough to all multiple columns
+ inside \meta{header}. You will have to use a |tabular| or a |matrix| in
+ such cases.
+
+ One further note: Since the text of each line is placed in a box, settings
+ will be local to each ``line''. This is very similar to the way a cell in a
+ |tabular| or a |matrix| behaves.
+\end{key}
+
+
+\subsubsection{Text Parameters: Height and Depth of Text}
+
+In addition to changing the width of nodes, you can also change the height of
+nodes. This can be done in two ways: First, you can use the option
+|minimum height|, which ensures that the height of the whole node is at least
+the given height (this option is described in more detail later). Second, you
+can use the option |text height|, which sets the height of the text itself,
+more precisely, of the \TeX\ text box of the text. Note that the |text height|
+typically is not the height of the shape's box: In addition to the
+|text height|, an internal |inner sep| is added as extra space and the text
+depth is also taken into account.
+
+I recommend using |minimum size| instead of |text height| except for special
+situations.
+
+\begin{key}{/tikz/text height=\meta{dimension}}
+ Sets the height of the text boxes in shapes. Thus, when you write something
+ like |node {text}|, the |text| is first typeset, resulting in some box of a
+ certain height. This height is then replaced by the height |text height|.
+ The resulting box is then used to determine the size of the shape, which
+ will typically be larger. When you write |text height=| without specifying
+ anything, the ``natural'' size of the text box remains unchanged.
+ %
+\begin{codeexample}[]
+\tikz \node[draw] {y};
+\tikz \node[draw,text height=10pt] {y};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/text depth=\meta{dimension}}
+ This option works like |text height|, only for the depth of the text box.
+ This option is mostly useful when you need to ensure a uniform depth of
+ text boxes that need to be aligned.
+\end{key}
+
+
+\subsection{Positioning Nodes}
+\label{section-nodes-anchors}
+
+When you place a node at some coordinate, the node is centered on this
+coordinate by default. This is often undesirable and it would be better to have
+the node to the right or above the actual coordinate.
+
+
+\subsubsection{Positioning Nodes Using Anchors}
+
+\pgfname\ uses a so-called anchoring mechanism to give you a very fine control
+over the placement. The idea is simple: Imagine a node of rectangular shape of
+a certain size. \pgfname\ defines numerous anchor positions in the shape. For
+example to upper right corner is called, well, not ``upper right anchor'', but
+the |north east| anchor of the shape. The center of the shape has an anchor
+called |center| on top of it, and so on. Here are some examples (a complete
+list is given in Section~\ref{section-the-shapes}).
+
+\medskip\noindent
+\begin{tikzpicture}
+ \path node[minimum height=2cm,minimum width=5cm,fill=blue!25](x) {Big node};
+ \fill (x.north) circle (2pt) node[above] {|north|}
+ (x.north east) circle (2pt) node[above] {|north east|}
+ (x.north west) circle (2pt) node[above] {|north west|}
+ (x.west) circle (2pt) node[left] {|west|}
+ (x.east) circle (2pt) node[right] {|east|}
+ (x.base) circle (2pt) node[below] {|base|};
+\end{tikzpicture}
+
+Now, when you place a node at a certain coordinate, you can ask \tikzname\ to
+place the node shifted around in such a way that a certain anchor is at the
+coordinate. In the following example, we ask \tikzname\ to shift the first node
+such that its |north east| anchor is at coordinate |(0,0)| and that the |west|
+anchor of the second node is at coordinate |(1,1)|.
+%
+\begin{codeexample}[]
+\tikz \draw (0,0) node[anchor=north east] {first node}
+ rectangle (1,1) node[anchor=west] {second node};
+\end{codeexample}
+
+Since the default anchor is |center|, the default behavior is to shift the node
+in such a way that it is centered on the current position.
+
+\begin{key}{/tikz/anchor=\meta{anchor name}}
+ Causes the node to be shifted such that its anchor \meta{anchor name} lies
+ on the current coordinate.
+
+ The only anchor that is present in all shapes is |center|. However, most
+ shapes will at least define anchors in all ``compass directions''.
+ Furthermore, the standard shapes also define a |base| anchor, as well as
+ |base west| and |base east|, for placing things on the baseline of the
+ text.
+
+ The standard shapes also define a |mid| anchor (and |mid west| and
+ |mid east|). This anchor is half the height of the character ``x'' above
+ the base line. This anchor is useful for vertically centering multiple
+ nodes that have different heights and depth. Here is an example:
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}[scale=3,transform shape]
+ % First, center alignment -> wobbles
+ \draw[anchor=center] (0,1) node{x} -- (0.5,1) node{y} -- (1,1) node{t};
+ % Second, base alignment -> no wobble, but too high
+ \draw[anchor=base] (0,.5) node{x} -- (0.5,.5) node{y} -- (1,.5) node{t};
+ % Third, mid alignment
+ \draw[anchor=mid] (0,0) node{x} -- (0.5,0) node{y} -- (1,0) node{t};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+
+\subsubsection{Basic Placement Options}
+
+Unfortunately, while perfectly logical, it is often rather counter-intuitive
+that in order to place a node \emph{above} a given point, you need to specify
+the |south| anchor. For this reason, there are some useful options that allow
+you to select the standard anchors more intuitively:
+
+\begin{key}{/tikz/above=\meta{offset} (default 0pt)}
+ Does the same as |anchor=south|. If the \meta{offset} is specified, the
+ node is additionally shifted upwards by the given \meta{offset}.
+ %
+\begin{codeexample}[]
+\tikz \fill (0,0) circle (2pt) node[above] {above};
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\tikz \fill (0,0) circle (2pt) node[above=2pt] {above};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/below=\meta{offset} (default 0pt)}
+ Similar to |above|.
+\end{key}
+
+\begin{key}{/tikz/left=\meta{offset} (default 0pt)}
+ Similar to |above|.
+\end{key}
+
+\begin{key}{/tikz/right=\meta{offset} (default 0pt)}
+ Similar to |above|.
+\end{key}
+
+\begin{key}{/tikz/above left}
+ Does the same as |anchor=south east|. Note that giving both |above| and
+ |left| options does not have the same effect as |above left|, rather only
+ the last |left| ``wins''. Actually, this option also takes an \meta{offset}
+ parameter, but using this parameter without using the |positioning| library
+ is deprecated. (The |positioning| library changes the meaning of this
+ parameter to something more sensible.)
+ %
+\begin{codeexample}[]
+\tikz \fill (0,0) circle (2pt) node[above left] {above left};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/above right}
+ Similar to |above left|.
+ %
+\begin{codeexample}[]
+\tikz \fill (0,0) circle (2pt) node[above right] {above right};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/below left}
+ Similar to |above left|.
+\end{key}
+
+\begin{key}{/tikz/below right}
+ Similar to |above left|.
+\end{key}
+
+\begin{key}{/tikz/centered}
+ A shorthand for |anchor=center|.
+\end{key}
+
+% A second set of options behaves similarly, namely the |above of|,
+% |below of|, and so on options. They cause the same anchors to be set
+% as the options without |of|, however, their parameter is different:
+% You must provide the name of another node. The current node will then
+% be placed, say, above this specified node at a distance given by the
+% option |node distance|.
+% \begin{key}{/tikz/above of=\meta{node}}
+% This option causes the node to be placed at the distance
+% |node distance| above of \meta{node}. The anchor is |center|.
+% \begin{codeexample}[]
+% \begin{tikzpicture}[node distance=1cm]
+% \draw[help lines] (0,0) grid (3,2);
+% \node (a) {a};
+% \node (b) [above of=a] {b};
+% \node (c) [above of=b] {c};
+% \node (d) [right of=c] {d};
+% \node (e) [below right of=d] {e};
+% \end{tikzpicture}
+% \end{codeexample}
+% \end{key}
+%
+% \begin{key}{/tikz/above left of=\meta{node}}
+% Works like |above of|, only the node is now put above and left. The
+% |node distance| is the Euclidean distance between the two nodes, not
+% the $L_1$-distance.
+% \end{key}
+%
+% \begin{key}{/tikz/above right of=\meta{node}}
+% Works similarly.
+% \end{key}
+% \begin{key}{/tikz/left of=\meta{node}}
+% Works similarly.
+% \end{key}
+% \begin{key}{/tikz/right of=\meta{node}}
+% Works similarly.
+% \end{key}
+% \begin{key}{/tikz/below of=\meta{node}}
+% Works similarly.
+% \end{key}
+% \begin{key}{/tikz/below left of=\meta{node}}
+% Works similarly.
+% \end{key}
+% \begin{key}{/tikz/below right of=\meta{node}}
+% Works similarly.
+% \end{key}
+% \begin{key}{/tikz/node distance=\meta{dimension}}
+% Sets the distance between nodes that are placed using the
+% |... of| options. Note that this distance is the distance between
+% the centers of the nodes, not the distance between their borders.
+% \end{key}
+
+
+\subsubsection{Advanced Placement Options}
+
+While the standard placement options suffice for simple cases, the
+|positioning| library offers more convenient placement options.
+
+\begin{tikzlibrary}{positioning}
+ The library defines additional options for placing nodes conveniently. It
+ also redefines the standard options like |above| so that they give you
+ better control of node placement.
+\end{tikzlibrary}
+
+When this library is loaded, the options like |above| or |above left| behave
+differently.
+
+\begin{key}{/tikz/above=\opt{\meta{specification}} (default 0pt)}
+ With the |positioning| library loaded, the |above| option does not take a
+ simple \meta{dimension} as its parameter. Rather, it can (also) take a more
+ elaborate \meta{specification} as parameter. This \meta{specification} has
+ the following general form: It starts with an optional \meta{shifting part}
+ and is followed by an optional \meta{of-part}. Let us start with the
+ \meta{shifting part}, which can have three forms:
+ %
+ \begin{enumerate}
+ \item It can simply be a \declare{\meta{dimension}} (or a mathematical
+ expression that evaluates to a dimension) like |2cm| or
+ |3cm/2+4cm|. In this case, the following happens: the node's anchor
+ is set to |south| and the node is vertically shifted upwards by
+ \meta{dimension}.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (2,2);
+ \node at (1,1) [above=2pt+3pt,draw] {above};
+\end{tikzpicture}
+\end{codeexample}
+ %
+ This use of the |above| option is the same as if the |positioning|
+ library were not loaded.
+ \item It can be a \declare{\meta{number}} (that is, any mathematical
+ expression that does not include a unit like |pt| or |cm|).
+ Examples are |2| or |3+sin(60)|. In this case, the anchor is also
+ set to |south| and the node is vertically shifted by the vertical
+ component of the coordinate |(0,|\meta{number}|)|.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (2,2);
+ \node at (1,1) [above=.2,draw] {above};
+ % south border of the node is now 2mm above (1,1)
+\end{tikzpicture}
+\end{codeexample}
+ %
+ \item It can be of the form
+ \declare{\meta{number or dimension 1}| and |\meta{number or dimension 2}}.
+ This specification does not make particular sense for the |above|
+ option, it is much more useful for options like |above left|. The
+ reason it is allowed for the |above| option is that it is sometimes
+ automatically used, as explained later.
+
+ The effect of this option is the following. First, the point
+ |(|\meta{number or dimension 2}|,|\meta{number or dimension 1}|)|
+ is computed (note the inverted order), using the normal rules for
+ evaluating such a coordinate, yielding some position. Then, the
+ node is shifted by the vertical component of this point. The anchor
+ is set to |south|.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (2,2);
+ \node at (1,1) [above=.2 and 3mm,draw] {above};
+ % south border of the node is also 2mm above (1,1)
+\end{tikzpicture}
+\end{codeexample}
+ \end{enumerate}
+ %
+ The \meta{shifting part} can optionally be followed by a \meta{of-part},
+ which has one of the following forms:
+ %
+ \begin{enumerate}
+ \item The \meta{of-part} can be
+ \declareandlabel{of}| |\meta{coordinate}, where \meta{coordinate} is
+ \emph{not} in parentheses and it is \emph{not} just a node name. An
+ example would be |of somenode.north| or |of {2,3}|. In this case, the
+ following happens: First, the node's |at| parameter is set to the
+ \meta{coordinate}. Second, the node is shifted according to the
+ \meta{shift-part}. Third, the anchor is set to |south|.
+
+ Here is a basic example:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\begin{tikzpicture}[every node/.style=draw]
+ \draw[help lines] (0,0) grid (2,2);
+ \node (somenode) at (1,1) {some node};
+
+ \node [above=5mm of somenode.north east] {\tiny 5mm of somenode.north east};
+ \node [above=1cm of somenode.north] {\tiny 1cm of somenode.north};
+\end{tikzpicture}
+\end{codeexample}
+ %
+ As can be seen the |above=5mm of somenode.north east| option does,
+ indeed, place the node 5mm above the north east anchor of
+ |somenode|. The same effect could have been achieved writing
+ |above=5mm| followed by |at=(somenode.north east)|.
+
+ If the \meta{shifting-part} is missing, the shift is not zero, but
+ rather the value of the |node distance| key is used, see below.
+ \item The \meta{of-part} can be |of |\meta{node name}. An example would
+ be |of somenode|. In this case, the following usually happens:
+ %
+ \begin{itemize}
+ \item The anchor is set to |south|.
+ \item The node is shifted according to the \meta{shifting part}
+ or, if it is missing, according to the value of
+ |node distance|.
+ \item The node's |at| parameter is set to \meta{node
+ name}|.north|.
+ \end{itemize}
+ %
+ The net effect of all this is that the new node will be placed in
+ such a way that the distance between its south border and \meta{node
+ name}'s north border is exactly the given distance.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\begin{tikzpicture}[every node/.style=draw]
+ \draw[help lines] (0,0) grid (2,2);
+ \node (some node) at (1,1) {some node};
+
+ \node (other node) [above=1cm of some node] {\tiny above=1cm of some node};
+
+ \draw [<->] (some node.north) -- (other node.south)
+ node [midway,right,draw=none] {1cm};
+\end{tikzpicture}
+\end{codeexample}
+ %
+ It is possible to change the behavior of this \meta{specification}
+ rather drastically, using the following key:
+ %
+ \begin{key}{/tikz/on grid=\meta{boolean} (initially false)}
+ When this key is set to |true|, an \meta{of-part} of the
+ current form behaves differently: The anchors set for the
+ current node as well as the anchor used for the other
+ \meta{node name} are set to |center|.
+
+ This has the following effect: When you say
+ |above=1cm of somenode| with |on grid| set to true, the new
+ node will be placed in such a way that its center is 1cm above
+ the center of |somenode|. Repeatedly placing nodes in this way
+ will result in nodes that are centered on ``grid coordinate'',
+ hence the name of the option.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\begin{tikzpicture}[every node/.style=draw]
+ \draw[help lines] (0,0) grid (2,3);
+
+ % Not gridded
+ \node (a1) at (0,0) {not gridded};
+ \node (b1) [above=1cm of a1] {fooy};
+ \node (c1) [above=1cm of b1] {a};
+
+ % gridded
+ \node (a2) at (2,0) {gridded};
+ \node (b2) [on grid,above=1cm of a2] {fooy};
+ \node (c2) [on grid,above=1cm of b2] {a};
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+ \end{enumerate}
+
+ \begin{key}{/tikz/node distance=\meta{shifting part} (initially 1cm and 1cm)}
+ The value of this key is used as \meta{shifting part} is used if and
+ only if a \meta{of-part} is present, but no \meta{shifting part}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\begin{tikzpicture}[every node/.style=draw,node distance=5mm]
+ \draw[help lines] (0,0) grid (2,3);
+
+ % Not gridded
+ \node (a1) at (0,0) {not gridded};
+ \node (b1) [above=of a1] {fooy};
+ \node (c1) [above=of b1] {a};
+
+ % gridded
+ \begin{scope}[on grid]
+ \node (a2) at (2,0) {gridded};
+ \node (b2) [above=of a2] {fooy};
+ \node (c2) [above=of b2] {a};
+ \end{scope}
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+\end{key}
+
+\begin{key}{/tikz/below=\opt{\meta{specification}}}
+ This key is redefined in the same manner as |above|.
+\end{key}
+
+\begin{key}{/tikz/left=\opt{\meta{specification}}}
+ This key is redefined in the same manner as |above|, only all vertical
+ shifts are replaced by horizontal shifts.
+\end{key}
+
+\begin{key}{/tikz/right=\opt{\meta{specification}}}
+ This key is redefined in the same manner as |left|.
+\end{key}
+
+\begin{key}{/tikz/above left=\opt{\meta{specification}}}
+ This key is also redefined in a manner similar to the above, but behavior
+ of the \meta{shifting part} is more complicated:
+ %
+ \begin{enumerate}
+ \item When the \meta{shifting part} is of the form
+ \meta{number or dimension}| and |\meta{number or dimension}, it has
+ (essentially) the effect of shifting the node vertically upwards by
+ the first \meta{number or dimension} and to the left by the second.
+ To be more precise, the coordinate |(|\meta{second number or
+ dimension}|,|\meta{first number or dimension}|)| is computed and
+ then the node is shifted vertically by the $y$-part of the
+ resulting coordinate and horizontally be the negated $x$-part of
+ the result. (This is exactly what you expect, except possibly when
+ you have used the |x| and |y| options to modify the |xy|-coordinate
+ system so that the unit vectors no longer point in the expected
+ directions.)
+ \item When the \meta{shifting part} is of the form \meta{number or
+ dimension}, the node is shifted by this \meta{number or dimension}
+ in the direction of $135^\circ$. This means that there is a
+ difference between a \meta{shifting part} of |1cm| and of
+ |1cm and 1cm|: In the second case, the node is shifted by 1cm
+ upward and 1cm to the left; in the first case it is shifted by
+ $\frac{1}{2}\sqrt{2}$cm upward and by the same amount to the left.
+ A more mathematical way of phrasing this is the following: A plain
+ \meta{dimension} is measured in the $l_2$-norm, while a
+ \meta{dimension}| and |\meta{dimension} is measured in the
+ $l_1$-norm.
+ \end{enumerate}
+ %
+ The following example should help to illustrate the difference:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\begin{tikzpicture}[every node/.style={draw,circle}]
+ \draw[help lines] (0,0) grid (2,5);
+ \begin{scope}[node distance=5mm and 5mm]
+ \node (b) at (1,4) {b};
+ \node [left=of b] {1}; \node [right=of b] {2};
+ \node [above=of b] {3}; \node [below=of b] {4};
+ \node [above left=of b] {5}; \node [above right=of b] {6};
+ \node [below left=of b] {7}; \node [below right=of b] {8};
+ \end{scope}
+ \begin{scope}[node distance=5mm]
+ \node (a) at (1,1) {a};
+ \node [left=of a] {1}; \node [right=of a] {2};
+ \node [above=of a] {3}; \node [below=of a] {4};
+ \node [above left=of a] {5}; \node [above right=of a] {6};
+ \node [below left=of a] {7}; \node [below right=of a] {8};
+ \end{scope}
+\end{tikzpicture}
+\end{codeexample}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\begin{tikzpicture}[every node/.style={draw,rectangle}]
+ \draw[help lines] (0,0) grid (2,5);
+ \begin{scope}[node distance=5mm and 5mm]
+ \node (b) at (1,4) {b};
+ \node [left=of b] {1}; \node [right=of b] {2};
+ \node [above=of b] {3}; \node [below=of b] {4};
+ \node [above left=of b] {5}; \node [above right=of b] {6};
+ \node [below left=of b] {7}; \node [below right=of b] {8};
+ \end{scope}
+ \begin{scope}[node distance=5mm]
+ \node (a) at (1,1) {a};
+ \node [left=of a] {1}; \node [right=of a] {2};
+ \node [above=of a] {3}; \node [below=of a] {4};
+ \node [above left=of a] {5}; \node [above right=of a] {6};
+ \node [below left=of a] {7}; \node [below right=of a] {8};
+ \end{scope}
+\end{tikzpicture}
+\end{codeexample}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\begin{tikzpicture}[every node/.style={draw,rectangle},on grid]
+ \draw[help lines] (0,0) grid (4,4);
+ \begin{scope}[node distance=1]
+ \node (a) at (2,3) {a};
+ \node [left=of a] {1}; \node [right=of a] {2};
+ \node [above=of a] {3}; \node [below=of a] {4};
+ \node [above left=of a] {5}; \node [above right=of a] {6};
+ \node [below left=of a] {7}; \node [below right=of a] {8};
+ \end{scope}
+ \begin{scope}[node distance=1 and 1]
+ \node (b) at (2,0) {b};
+ \node [left=of b] {1}; \node [right=of b] {2};
+ \node [above=of b] {3}; \node [below=of b] {4};
+ \node [above left=of b] {5}; \node [above right=of b] {6};
+ \node [below left=of b] {7}; \node [below right=of b] {8};
+ \end{scope}
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/below left=\opt{\meta{specification}}}
+ Works similar to |above left|.
+\end{key}
+
+\begin{key}{/tikz/above right=\opt{\meta{specification}}}
+ Works similar to |above left|.
+\end{key}
+
+\begin{key}{/tikz/below right=\opt{\meta{specification}}}
+ Works similar to |above left|.
+\end{key}
+
+The |positioning| package also introduces the following new placement keys:
+%
+\begin{key}{/tikz/base left=\opt{\meta{specification}}}
+ This key works like the |left| key, only instead of the |east| anchor, the
+ |base east| anchor is used and, when the second form of an \meta{of-part}
+ is used, the corresponding |base west| anchor.
+
+ This key is useful for chaining together nodes so that their base lines are
+ aligned.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\begin{tikzpicture}[node distance=1ex]
+ \draw[help lines] (0,0) grid (3,1);
+ \huge
+ \node (X) at (0,1) {X};
+ \node (a) [right=of X] {a};
+ \node (y) [right=of a] {y};
+
+ \node (X) at (0,0) {X};
+ \node (a) [base right=of X] {a};
+ \node (y) [base right=of a] {y};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/base right=\opt{\meta{specification}}}
+ Works like |base left|.
+\end{key}
+\begin{key}{/tikz/mid left=\opt{\meta{specification}}}
+ Works like |base left|, but with |mid east| and |mid west| anchors instead
+ of |base east| and |base west|.
+\end{key}
+
+\begin{key}{/tikz/mid right=\opt{\meta{specification}}}
+ Works like |mid left|.
+\end{key}
+
+
+\subsubsection{Advanced Arrangements of Nodes}
+
+The simple |above| and |right| options may not always suffice for arranging a
+large number of nodes. For such situations \tikzname\ offers libraries that
+make positioning easier: The |matrix| library and the |graphdrawing| library.
+These libraries for positioning nodes are described in two separate
+Sections~\ref{section-matrices} and~\ref{section-intro-gd}.
+
+
+\subsection{Fitting Nodes to a Set of Coordinates}
+\label{section-nodes-fitting}
+
+It is sometimes desirable that the size and position of a node is not given
+using anchors and size parameters, rather one would sometimes have a box be
+placed and be sized such that it ``is just large enough to contain this, that,
+and that point''. This situation typically arises when a picture has been drawn
+and, afterwards, parts of the picture are supposed to be encircled or
+highlighted.
+
+In this situation the |fit| option from the |fit| library is useful, see
+Section~\ref{section-library-fit} for the details. The idea is that you may
+give the |fit| option to a node. The |fit| option expects a list of coordinates
+(one after the other without commas) as its parameter. The effect will be that
+the node's text area has exactly the necessary size so that it contains all the
+given coordinates. Here is an example:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{fit,shapes.geometric}}]
+\begin{tikzpicture}[level distance=8mm]
+ \node (root) {root}
+ child { node (a) {a} }
+ child { node (b) {b}
+ child { node (d) {d} }
+ child { node (e) {e} } }
+ child { node (c) {c} };
+
+ \node[draw=red,inner sep=0pt,thick,ellipse,fit=(root) (b) (d) (e)] {};
+ \node[draw=blue,inner sep=0pt,thick,ellipse,fit=(b) (c) (e)] {};
+\end{tikzpicture}
+\end{codeexample}
+
+If you want to fill the fitted node you will usually have to place it on a
+background layer.
+%
+\begin{codeexample}[preamble={\usetikzlibrary{backgrounds,fit,shapes.geometric}}]
+\begin{tikzpicture}[level distance=8mm]
+ \node (root) {root}
+ child { node (a) {a} }
+ child { node (b) {b}
+ child { node (d) {d} }
+ child { node (e) {e} } }
+ child { node (c) {c} };
+
+ \begin{scope}[on background layer]
+ \node[fill=red!20,inner sep=0pt,ellipse,fit=(root) (b) (d) (e)] {};
+ \node[fill=blue!20,inner sep=0pt,ellipse,fit=(b) (c) (e)] {};
+ \end{scope}
+\end{tikzpicture}
+\end{codeexample}
+
+
+\subsection{Transformations}
+\label{section-nodes-transformations}
+
+It is possible to transform nodes, but, by default, transformations do not
+apply to nodes. The reason is that you usually do \emph{not} want your text to
+be scaled or rotated even if the main graphic is transformed. Scaling text is
+evil, rotating slightly less so.
+
+However, sometimes you \emph{do} wish to transform a node, for example, it
+certainly sometimes makes sense to rotate a node by 90 degrees. There are two
+ways to achieve this:
+%
+\begin{enumerate}
+ \item You can use the following option:
+ %
+ \begin{key}{/tikz/transform shape}
+ Causes the current ``external'' transformation matrix to be applied
+ to the shape. For example, if you said |\tikz[scale=3]| and then
+ say |node[transform shape] {X}|, you will get a ``huge'' X in your
+ graphic.
+ \end{key}
+ \item You can give transformation options \emph{inside} the option list of
+ the node. \emph{These} transformations always apply to the node.
+ %
+\begin{codeexample}[
+ preamble={\usepgfmodule{nonlineartransformations}\usetikzlibrary{curvilinear}},
+ pre={\makeatletter},
+]
+\begin{tikzpicture}[every node/.style={draw}]
+ \draw[help lines](0,0) grid (3,2);
+ \draw (1,0) node{A}
+ (2,0) node[rotate=90,scale=1.5] {B};
+ \draw[rotate=30] (1,0) node{A}
+ (2,0) node[rotate=90,scale=1.5] {B};
+ \draw[rotate=60] (1,0) node[transform shape] {A}
+ (2,0) node[transform shape,rotate=90,scale=1.5] {B};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{enumerate}
+
+Even though \tikzname\ currently does not allow you to configure so-called
+\emph{nonlinear transformations,} see
+Section~\ref{section-nonlinear-transformations}, there is an option that
+influences how nodes are transformed when nonlinear transformations are in
+force:
+%
+\begin{key}{/tikz/transform shape nonlinear=\opt{\meta{true or false}} (initially false)}
+ When set to true, \tikzname\ will try to apply any current nonlinear
+ transformation also to nodes. Typically, for the text in nodes this is not
+ possible in general, in such cases a linear approximation of the nonlinear
+ transformation is used. For more details, see
+ Section~\ref{section-nonlinear-transformations}.
+ %
+\makeatletter
+\begin{codeexample}[
+ preamble={\usepgfmodule{nonlineartransformations}\usetikzlibrary{curvilinear}},
+ pre={\makeatletter},
+]
+\begin{tikzpicture}
+ % Install a nonlinear transformation:
+ \pgfsetcurvilinearbeziercurve
+ {\pgfpoint{0mm}{20mm}}
+ {\pgfpoint{10mm}{20mm}}
+ {\pgfpoint{10mm}{10mm}}
+ {\pgfpoint{20mm}{10mm}}
+ \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}%
+
+ % Draw something:
+ \draw [help lines] (0,-30pt) grid [step=10pt] (80pt,30pt);
+
+ \foreach \x in {0,20,...,80}
+ \node [fill=red!20] at (\x pt, -20pt) {\x};
+
+ \foreach \x in {0,20,...,80}
+ \node [fill=blue!20, transform shape nonlinear] at (\x pt, 20pt) {\x};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+
+\subsection{Placing Nodes on a Line or Curve Explicitly}
+\label{section-nodes-placing-1}
+
+Until now, we always placed nodes on a coordinate that is mentioned in the path.
+Often, however, we wish to place nodes on ``the middle'' of a line and we do
+not wish to compute these coordinates ``by hand''. To facilitate such
+placements, \tikzname\ allows you to specify that a certain node should be
+somewhere ``on'' a line. There are two ways of specifying this: Either
+explicitly by using the |pos| option or implicitly by placing the node
+``inside'' a path operation. These two ways are described in the following.
+
+ \label{section-pos-option}
+
+\begin{key}{/tikz/pos=\meta{fraction}}
+ When this option is given, the node is not anchored on the last coordinate.
+ Rather, it is anchored on some point on the line from the previous
+ coordinate to the current point. The \meta{fraction} dictates how ``far''
+ on the line the point should be. A \meta{fraction} of 0 is the previous
+ coordinate, 1 is the current one, everything else is in between. In
+ particular, 0.5 is the middle.
+
+ Now, what is ``the previous line''? This depends on the previous path
+ construction operation.
+
+ In the simplest case, the previous path operation was a ``line-to''
+ operation, that is, a |--|\meta{coordinate} operation:
+ %
+\begin{codeexample}[]
+\tikz \draw (0,0) -- (3,1)
+ node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10};
+\end{codeexample}
+
+ For the |arc| operation, the position is simply the corresponding position
+ on the arc:
+ %
+\begin{codeexample}[]
+\tikz {
+ \draw [help lines] (0,0) grid (3,2);
+ \draw (2,0) arc [x radius=1, y radius=2, start angle=0, end angle=180]
+ node foreach \t in {0,0.125,...,1} [pos=\t,auto] {\t};
+}
+\end{codeexample}
+
+ The next case is the curve-to operation (the |..| operation). In this case,
+ the ``middle'' of the curve, that is, the position |0.5| is not necessarily
+ the point at the exact half distance on the line. Rather, it is some point
+ at ``time'' 0.5 of a point traveling from the start of the curve, where it
+ is at time 0, to the end of the curve, which it reaches at time 0.5. The
+ ``speed'' of the point depends on the length of the support vectors (the
+ vectors that connect the start and end points to the control points). The
+ exact math is a bit complicated (depending on your point of view, of
+ course); you may wish to consult a good book on computer graphics and
+ Bézier curves if you are intrigued.
+ %
+\begin{codeexample}[]
+\tikz \draw (0,0) .. controls +(right:3.5cm) and +(right:3.5cm) .. (0,3)
+ node foreach \p in {0,0.125,...,1} [pos=\p]{\p};
+\end{codeexample}
+
+ Another interesting case are the horizontal/vertical line-to operations
+ \verb!|-! and \verb!-|!. For them, the position (or time) |0.5| is exactly
+ the corner point.
+ %
+\begin{codeexample}[]
+\tikz \draw (0,0) |- (3,1)
+ node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10};
+\end{codeexample}
+
+\begin{codeexample}[]
+\tikz \draw (0,0) -| (3,1)
+ node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10};
+\end{codeexample}
+
+ For all other path construction operations, \emph{the position placement
+ does not work}, currently.
+\end{key}
+
+\begin{key}{/tikz/auto=\opt{\meta{direction}} (default \normalfont is scope's setting)}
+ This option causes an anchor position to be calculated automatically
+ according to the following rule. Consider a line between two points. If the
+ \meta{direction} is |left|, then the anchor is chosen such that the node is
+ to the left of this line. If the \meta{direction} is |right|, then the node
+ is to the right of this line. Leaving out \meta{direction} causes automatic
+ placement to be enabled with the last value of |left| or |right| used. A
+ \meta{direction} of |false| disables automatic placement. This happens also
+ whenever an anchor is given explicitly by the |anchor| option or by one of
+ the |above|, |below|, etc.\ options.
+
+ This option only has an effect for nodes that are placed on lines or
+ curves.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ [scale=.8,auto=left,every node/.style={circle,fill=blue!20}]
+ \node (a) at (-1,-2) {a};
+ \node (b) at ( 1,-2) {b};
+ \node (c) at ( 2,-1) {c};
+ \node (d) at ( 2, 1) {d};
+ \node (e) at ( 1, 2) {e};
+ \node (f) at (-1, 2) {f};
+ \node (g) at (-2, 1) {g};
+ \node (h) at (-2,-1) {h};
+
+ \foreach \from/\to in {a/b,b/c,c/d,d/e,e/f,f/g,g/h,h/a}
+ \draw [->] (\from) -- (\to)
+ node[midway,fill=red!20] {\from--\to};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/swap}
+ This option exchanges the roles of |left| and |right| in automatic
+ placement. That is, if |left| is the current |auto| placement, |right| is
+ set instead and the other way round.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{automata}}]
+\begin{tikzpicture}[auto]
+ \draw[help lines,use as bounding box] (0,-.5) grid (4,5);
+
+ \draw (0.5,0) .. controls (9,6) and (-5,6) .. (3.5,0)
+ node foreach \pos in {0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1}
+ [pos=\pos,swap,fill=red!20] {\pos}
+ node foreach \pos in {0.025,0.2,0.4,0.6,0.8,0.975}
+ [pos=\pos,fill=blue!20] {\pos};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{automata}}]
+\begin{tikzpicture}[shorten >=1pt,node distance=2cm,auto]
+ \draw[help lines] (0,0) grid (3,2);
+
+ \node[state] (q_0) {$q_0$};
+ \node[state] (q_1) [above right of=q_0] {$q_1$};
+ \node[state] (q_2) [below right of=q_0] {$q_2$};
+ \node[state] (q_3) [below right of=q_1] {$q_3$};
+
+ \path[->] (q_0) edge node {0} (q_1)
+ edge node [swap] {1} (q_2)
+ (q_1) edge node {1} (q_3)
+ edge [loop above] node {0} ()
+ (q_2) edge node [swap] {0} (q_3)
+ edge [loop below] node {1} ();
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/'}
+ This is a very short alias for |swap|.
+\end{key}
+
+\begin{key}{/tikz/sloped}
+ This option causes the node to be rotated such that a horizontal line
+ becomes a tangent to the curve. The rotation is normally done in such a way
+ that text is never ``upside down''. To get upside-down text, use can use
+ |[rotate=180]| or |[allow upside down]|, see below.
+ %
+\begin{codeexample}[]
+\tikz \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3)
+ node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p};
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}[->]
+ \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$};
+ \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+
+\begin{key}{/tikz/allow upside down=\meta{boolean} (default true, initially false)}
+ If set to |true|, \tikzname\ will not ``righten'' upside down text.
+ %
+\begin{codeexample}[]
+\tikz [allow upside down]
+ \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3)
+ node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p};
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}[->,allow upside down]
+ \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$};
+ \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+There exist styles for specifying positions a bit less ``technically'':
+
+\begin{stylekey}{/tikz/midway}
+ This has the same effect as |pos=0.5|.
+ %
+\begin{codeexample}[]
+\tikz \draw (0,0) .. controls +(up:2cm) and +(left:3cm) .. (1,5)
+ node[at end] {\texttt{at end}}
+ node[very near end] {\texttt{very near end}}
+ node[near end] {\texttt{near end}}
+ node[midway] {\texttt{midway}}
+ node[near start] {\texttt{near start}}
+ node[very near start] {\texttt{very near start}}
+ node[at start] {\texttt{at start}};
+\end{codeexample}
+ %
+\end{stylekey}
+
+\begin{stylekey}{/tikz/near start}
+ Set to |pos=0.25|.
+\end{stylekey}
+
+\begin{stylekey}{/tikz/near end}
+ Set to |pos=0.75|.
+\end{stylekey}
+
+\begin{stylekey}{/tikz/very near start}
+ Set to |pos=0.125|.
+\end{stylekey}
+
+\begin{stylekey}{/tikz/very near end}
+ Set to |pos=0.875|.
+\end{stylekey}
+
+\begin{stylekey}{/tikz/at start}
+ Set to |pos=0|.
+\end{stylekey}
+
+\begin{stylekey}{/tikz/at end}
+ Set to |pos=1|.
+\end{stylekey}
+
+
+\subsection{Placing Nodes on a Line or Curve Implicitly}
+\label{section-nodes-placing-2}
+
+When you wish to place a node on the line |(0,0) -- (1,1)|, it is natural to
+specify the node not following the |(1,1)|, but ``somewhere in the middle''.
+This is, indeed, possible and you can write |(0,0) -- node{a} (1,1)| to place a
+node midway between |(0,0)| and |(1,1)|.
+
+What happens is the following: The syntax of the line-to path operation is
+actually |--| \opt{|node|\meta{node specification}}\meta{coordinate}. (It is
+even possible to give multiple nodes in this way.) When the optional |node| is
+encountered, that is, when the |--| is directly followed by |node|, then the
+specification(s) are read and ``stored away''. Then, after the
+\meta{coordinate} has finally been reached, they are inserted again, but with
+the |pos| option set.
+
+There are two things to note about this: When a node specification is
+``stored'', its catcodes become fixed. This means that you cannot use overly
+complicated verbatim text in them. If you really need, say, a verbatim text,
+you will have to put it in a normal node following the coordinate and add the
+|pos| option.
+
+Second, which |pos| is chosen for the node? The position is inherited from the
+surrounding scope. However, this holds only for nodes specified in this
+implicit way. Thus, if you add the option |[near end]| to a scope, this does
+not mean that \emph{all} nodes given in this scope will be put on near the end
+of lines. Only the nodes for which an implicit |pos| is added will be placed
+near the end. Typically, this is what you want. Here are some examples that
+should make this clearer:
+%
+\begin{codeexample}[]
+\begin{tikzpicture}[near end]
+ \draw (0cm,4em) -- (3cm,4em) node{A};
+ \draw (0cm,3em) -- node{B} (3cm,3em);
+ \draw (0cm,2em) -- node[midway] {C} (3cm,2em);
+ \draw (0cm,1em) -- (3cm,1em) node[midway] {D} ;
+\end{tikzpicture}
+\end{codeexample}
+
+Like the line-to operation, the curve-to operation |..| also allows you to
+specify nodes ``inside'' the operation. After both the first |..| and also
+after the second |..| you can place node specifications. Like for the |--|
+operation, these will be collected and then reinserted after the operation with
+the |pos| option set.
+
+
+\subsection{The Label and Pin Options}
+
+\subsubsection{Overview}
+
+In addition to the |node| path operation, the two options |label| and |pin| can
+be used to ``add a node next to another node''. As an example, suppose we want
+to draw a graph in which the nodes are small circles:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\tikz [circle] {
+ \node [draw] (s) {};
+ \node [draw] (a) [right=of s] {} edge (s);
+ \node [draw] (b) [right=of a] {} edge (a);
+ \node [draw] (t) [right=of b] {} edge (b);
+}
+\end{codeexample}
+
+Now, in the above example, suppose we wish to indicate that the first node is
+the start node and the last node is the target node. We could write
+|\node (s) {$s$};|, but this would enlarge the first node. Rather, we want the
+``$s$'' to be placed next to the node. For this, we need to create
+\emph{another} node, but next to the existing node. The |label| and |pin|
+option allow us to do exactly this without having to use the cumbersome |node|
+syntax:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
+\tikz [circle] {
+ \node [draw] (s) [label=$s$] {};
+ \node [draw] (a) [right=of s] {} edge (s);
+ \node [draw] (b) [right=of a] {} edge (a);
+ \node [draw] (t) [right=of b, label=$t$] {} edge (b);
+}
+\end{codeexample}
+
+
+\subsubsection{The Label Option}
+
+\begin{key}{/tikz/label=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}}
+ \label{label-option}%
+ When this option is given to a |node| operation, it causes \emph{another}
+ node to be added to the path after the current node has been finished. This
+ extra node will have the text \meta{text}. It is placed, in principle, in
+ the direction \meta{angle} relative to the main node, but the exact rules
+ are a bit complex. Suppose the |node| currently under construction is
+ called |main node| and let us call the label node |label node|. Then the
+ following happens:
+ %
+ \begin{enumerate}
+ \item The \meta{angle} is used to determine a position on the border of
+ the |main node|. If the \meta{angle} is missing, the value of the
+ following key is used instead:
+ %
+ \begin{key}{/tikz/label position=\meta{angle} (initially above)}
+ Sets the default position for labels.
+ \end{key}
+ %
+ The \meta{angle} determines the position on the border of the shape
+ in two different ways. Normally, the border position is given by
+ |main node.|\meta{angle}. This means that the \meta{angle} can
+ either be a number like |0| or |-340|, but it can also be an anchor
+ like |north|. Additionally, the special angles |above|, |below|,
+ |left|, |right|, |above left|, and so on are automatically replaced
+ by the corresponding angles |90|, |270|, |180|, |0|, |135|, and so
+ on.
+
+ A special case arises when the following key is set:
+ %
+ \begin{key}{/tikz/absolute=\meta{true or false} (default true)}
+ When this key is set, the \meta{angle} is interpreted
+ differently: We still use a point on the border of the
+ |main node|, but the angle is measured ``absolutely'', that is,
+ an angle of |0| refers to the point on the border that lies on
+ a straight line from the |main node|'s center to the right
+ (relative to the paper, not relative to the local coordinate
+ system of either the node or the scope).
+
+ The difference can be seen in the following example:
+ %
+\begin{codeexample}[]
+\tikz [rotate=-80,every label/.style={draw,red}]
+ \node [transform shape,rectangle,draw,label=right:label] {main node};
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\tikz [rotate=-80,every label/.style={draw,red},absolute]
+ \node [transform shape,rectangle,draw,label=right:label] {main node};
+\end{codeexample}
+ \end{key}
+ \item Then, an anchor point for the |label node| is computed. It is
+ determined in such a way that the |label node| will ``face away''
+ from the border of the |main node|. The anchor that is chosen
+ depends on the position of the border point that is chosen and its
+ position relative to the center of the |main node| and on whether
+ the |transform shape| option is set. In detail, when the computed
+ border point is at $0^\circ$, the anchor |west| will be used.
+ Similarly, when the border point is at $90^\circ$, the anchor
+ |south| will be used, and so on for $180^\circ$ and $270^\circ$.
+
+ For angles between these ``major'' angles, like $30^\circ$ or
+ $110^\circ$, combined anchors, like |south west| for $30^\circ$ or
+ |south east| for $110^\circ$, are used. However, for angles close
+ to the major angles, (differing by up to $2^\circ$ from the major
+ angle), the anchor for the major angle is used. Thus, a label at a
+ border point for $2^\circ$ will have the anchor |west|, while a
+ label for $3^\circ$ will have the anchor |south west|, resulting in
+ a ``jump'' of the anchor. You can set the anchor ``by hand'' using
+ the |anchor| key or indirect keys like |left|.
+ %
+\begin{codeexample}[]
+\tikz
+ \node [circle, draw,
+ label=default,
+ label=60:$60^\circ$,
+ label=below:$-90^\circ$,
+ label=3:$3^\circ$,
+ label=2:$2^\circ$,
+ label={[below]180:$180^\circ$},
+ label={[centered]135:$135^\circ$}] {my circle};
+\end{codeexample}
+ \item One \meta{angle} is special: If you set the \meta{angle} to
+ |center|, then the label will be placed on the center of the main
+ node. This is mainly useful for adding a label text to an existing
+ node, especially if it has been rotated.
+ %
+\begin{codeexample}[]
+\tikz \node [transform shape,rotate=90,
+ rectangle,draw,label={[red]center:R}] {main node};
+\end{codeexample}
+ \end{enumerate}
+
+ You can pass \meta{options} to the node |label node|. For this, you provide
+ the options in square brackets before the \meta{angle}. If you do so, you
+ need to add braces around the whole argument of the |label| option and this
+ is also the case if you have brackets or commas or semicolons or anything
+ special in the \meta{text}.
+ %
+\begin{codeexample}[]
+\tikz \node [circle,draw,label={[red]above:X}] {my circle};
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node [circle,draw,label={[name=label node]above left:$a,b$}] {};
+ \draw (label node) -- +(1,1);
+\end{tikzpicture}
+\end{codeexample}
+
+ If you provide multiple |label| options, then multiple extra label nodes
+ are added in the order they are given.
+
+ The following styles influence how labels are drawn:
+ %
+ \begin{key}{/tikz/label distance=\meta{distance} (initially 0pt)}
+ The \meta{distance} is additionally inserted between the main node and
+ the label node.
+ %
+\begin{codeexample}[]
+\tikz[label distance=5mm]
+ \node [circle,draw,label=right:X,
+ label=above right:Y,
+ label=above:Z] {my circle};
+\end{codeexample}
+ \end{key}
+ %
+ \begin{stylekey}{/tikz/every label (initially \normalfont empty)}
+ This style is used in every node created by the |label| option. The
+ default is |draw=none,fill=none|.
+ \end{stylekey}
+\end{key}
+
+See Section~\ref{section-label-quotes} for an easier syntax for specifying
+nodes.
+
+
+\subsubsection{The Pin Option}
+
+\begin{key}{/tikz/pin=\opt{|[|\meta{options}|]|}\meta{angle}|:|\meta{text}}
+ This option is quite similar to the |label| option, but there is one
+ difference: In addition to adding an extra node to the picture, it also
+ adds an edge from this node to the main node. This causes the node to look
+ like a pin that has been added to the main node:
+ %
+\begin{codeexample}[]
+\tikz \node [circle,fill=blue!50,minimum size=1cm,pin=60:$q_0$] {};
+\end{codeexample}
+
+ The meaning of the \meta{options} and the \meta{angle} and the \meta{text}
+ is exactly the same as for the |node| option. Only, the options and styles
+ the influence the way pins look are different:
+ %
+ \begin{key}{/tikz/pin distance=\meta{distance} (initially 3ex)}
+ This \meta{distance} is used instead of the |label distance| for the
+ distance between the main node and the label node.
+ %
+\begin{codeexample}[]
+\tikz[pin distance=1cm]
+ \node [circle,draw,pin=right:X,
+ pin=above right:Y,
+ pin=above:Z] {my circle};
+\end{codeexample}
+ %
+ \end{key}
+
+ \begin{stylekey}{/tikz/every pin (initially {draw=none,fill=none})}
+ This style is used in every node created by the |pin| option.
+ \end{stylekey}
+
+ \begin{key}{/tikz/pin position=\meta{angle} (initially above)}
+ The default pin position. Works like |label position|.
+ \end{key}
+
+ \begin{stylekey}{/tikz/every pin edge (initially help lines)}
+ This style is used in every edge created by the |pin| options.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\tikz [pin distance=15mm,
+ every pin edge/.style={<-,shorten <=1pt,decorate,
+ decoration={snake,pre length=4pt}}]
+ \node [circle,draw,pin=right:X,
+ pin=above right:Y,
+ pin=above:Z] {my circle};
+\end{codeexample}
+ \end{stylekey}
+
+ \begin{key}{/tikz/pin edge=\meta{options} (initially \normalfont empty)}
+ This option can be used to set the options that are to be used in the
+ edge created by the |pin| option.
+ %
+\begin{codeexample}[]
+\tikz[pin distance=10mm]
+ \node [circle,draw,pin={[pin edge={blue,thick}]right:X},
+ pin=above:Z] {my circle};
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\tikz [every pin edge/.style={},
+ initial/.style={pin={[pin distance=5mm,
+ pin edge={<-,shorten <=1pt}]left:start}}]
+ \node [circle,draw,initial] {my circle};
+\end{codeexample}
+ \end{key}
+\end{key}
+
+
+\subsubsection{The Quotes Syntax}
+\label{section-label-quotes}
+
+The |label| and |pin| options provide a syntax for creating nodes next to
+existing nodes, but this syntax is often a bit too verbose. By including the
+following library, you get access to an even more concise syntax:
+
+\begin{tikzlibrary}{quotes}
+ Enables the quotes syntax for labels, pins, edge nodes, and pic texts.
+\end{tikzlibrary}
+
+Let us start with the basics of what this library does: Once loaded, inside the
+options of a |node| command, instead of the usual \meta{key}|=|\meta{value}
+pairs, you may also provide strings of the following form (the actual syntax is
+slightly more general, see the detailed descriptions later on):
+%
+\begin{quote}
+ |"|\meta{text}|"|\opt{\meta{options}}
+\end{quote}
+%
+The \meta{options} must be surrounded in curly braces when they contain a
+comma, otherwise the curly braces are optional. The \meta{options} may be
+preceded by an optional space.
+
+When a \meta{string} of the above form is encountered inside the options of a
+|node|, then it is internally transformed to
+%
+% (the double vertical bar after = is needed to avoid the two opening brackets
+% being typeset in italics)
+\begin{quote}
+ |label=||{[|\meta{options}|]|\meta{text}|}|
+\end{quote}
+
+Let us have a look at an example:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz \node ["my label" red, draw] {my node};
+\end{codeexample}
+%
+The above has the same effect as the following:
+%
+\begin{codeexample}[]
+\tikz \node [label={[red]my label}, draw] {my node};
+\end{codeexample}
+
+Here are further examples, one where no \meta{options} are added to the
+|label|, one where a position is specified, and examples with more complicated
+options in curly braces:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\begin{tikzpicture}
+ \matrix [row sep=5mm] {
+ \node [draw, "label"] {A}; \\
+ \node [draw, "label" left] {B}; \\
+ \node [draw, "label" centered] {C}; \\
+ \node [draw, "label" color=red] {D}; \\
+ \node [draw, "label" {red,draw,thick}] {E}; \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+Let us now have a more detailed look at what commands this library
+provides:
+
+\begin{key}{/tikz/quotes mean label}
+ When this option is used (which is the default when this library is
+ loaded), then, as described above, inside the options of a node a special
+ syntax check is done.
+
+ \medskip
+ \noindent\textbf{The syntax.}
+ For each string in the list of options it is tested whether it starts with
+ a quotation mark (note that this will never happen for normal keys since
+ the normal keys of \tikzname\ do not start with quotation marks). When this
+ happens, the \meta{string} should not be a key--value pair, but, rather,
+ must have the form:
+ %
+ \begin{quote}
+ |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}}
+ \end{quote}
+
+ (We will discuss the optional apostrophe in a moment. It is not really
+ important for the current option, but only for edge labels, which are
+ discussed later).
+
+ \medskip
+ \noindent\textbf{Transformation to a label option.}
+ When a \meta{string} has the above form, it is treated (almost) as if you
+ had written
+ %
+ \begin{quote}
+ |label={[|\meta{options}|]|\meta{text}|}|
+ \end{quote}
+ %
+ instead. The ``almost'' refers to the following additional feature: In
+ reality, before the \meta{options} are executed inside the |label| command,
+ the direction keys |above|, |left|, |below right| and so on are redefined
+ so that |above| is a shorthand for |label position=90| and similarly for
+ the other keys. The net effect is that in order to specify the position of
+ the \meta{text} relative to the main node you can just put something like
+ |left| or |above right| inside the \meta{options}:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz
+ \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle};
+\end{codeexample}
+
+ Alternatively, you can also use \meta{direction}|:|\meta{actual text} as
+ your \meta{text}. This works since the |label| command allows you to
+ specify a direction at the beginning when it is separated by a colon:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz
+ \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle};
+\end{codeexample}
+ %
+ Arguably, placing |above| or |left| behind the \meta{text} seems more
+ natural than having it inside the \meta{text}.
+
+ In addition to the above, before the \meta{options} are executed, the
+ following style is also executed:
+ %
+ \begin{stylekey}{/tikz/every label quotes}
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz [every label quotes/.style=red]
+ \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle};
+\end{codeexample}
+ \end{stylekey}
+
+ \medskip
+ \noindent\textbf{Handling commas and colons inside the text.}
+ The \meta{text} may not contain a comma, unless it is inside curly braces.
+ The reason is that the key handler separates the total options of a |node|
+ along the commas it finds. So, in order to have text containing a comma,
+ just add curly braces around either the comma or just around the whole
+ \meta{text}:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz \node ["{yes, we can}", draw] {foo};
+\end{codeexample}
+ %
+ The same is true for a colon, only in this case you may need to surround
+ specifically the colon by curly braces to stop the |label| option from
+ interpreting everything before the colon as a direction:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz \node ["yes{:} we can", draw] {foo};
+\end{codeexample}
+
+ \medskip
+ \noindent\textbf{The optional apostrophe.}
+ Following the closing quotation marks in a \meta{string} there may (but
+ need not) be a single quotation mark (an apostrophe), possibly surrounded
+ by whitespaces. If it is present, it is simply added to the \meta{options}
+ as another option (and, indeed, a single apostrophe is a legal option in
+ \tikzname, it is a shorthand for |swap|):
+
+ \begin{tabular}{ll}
+ String & has the same effect as \\\hline
+ |"foo"'| & |"foo" {'}| \\
+ |"foo"' red| & |"foo" {',red}| \\
+ |"foo"'{red}| & |"foo" {',red}| \\
+ |"foo"{',red}| & |"foo" {',red}| \\
+ |"foo"{red,'}| & |"foo" {red,'}| \\
+ |"foo"{'red}| & |"foo" {'red}| (illegal; there is no key |'red|)\\
+ |"foo" red'| & |"foo" {red'}| (illegal; there is no key |red'|)\\
+ \end{tabular}
+\end{key}
+
+\begin{key}{/tikz/quotes mean pin}
+ This option has exactly the same effect as |quotes mean label|, only
+ instead of transforming quoted text to the |label| option, they get
+ transformed to the |pin| option:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz [quotes mean pin]
+ \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle};
+\end{codeexample}
+ %
+ Instead of |every label quotes|, the following style is executed
+ with each such pin:
+ %
+ \begin{stylekey}{/tikz/every pin quotes}
+ \end{stylekey}
+\end{key}
+
+If instead of |label|s or |pin|s you would like quoted strings to be
+interpreted in a different manner, you can also define your own handlers:
+
+\begin{key}{/tikz/node quotes mean=\meta{replacement}}
+ This key allows you to define your own handler for quotes options. Inside
+ the options of a |node|, whenever a key--value pair with the syntax
+ %
+ \begin{quote}
+ |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}}
+ \end{quote}
+ %
+ is encountered, the following happens: The above string gets replaced by
+ \meta{replacement} where inside the \meta{replacement} the parameter |#1|
+ is \meta{text} and |#2| is \meta{options}. If the apostrophe is present
+ (see also the discussion of |quotes mean label|), the \meta{options} start
+ with |',|.
+
+ The \meta{replacement} is then parsed normally as options (using
+ |\pgfkeys|).
+
+ Here is an example, where the quotes are used to define labels that are
+ automatically named according to the |text|:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikzset{node quotes mean={label={[#2,name={#1}]#1}}}
+
+\tikz {
+ \node ["1", "2" label position=left, circle, draw] {circle};
+ \draw (1) -- (2);
+}
+\end{codeexample}
+ %
+\end{key}
+
+Some further options provided by the |quotes| library concern labels next to
+edges rather than nodes and they are described in
+Section~\ref{section-edge-quotes}.
+
+
+\subsection{Connecting Nodes: Using Nodes as Coordinates}
+\label{section-nodes-connecting}
+
+Once you have defined a node and given it a name, you can use this name to
+reference it. This can be done in two ways, see also
+Section~\ref{section-node-coordinates}. Suppose you have said
+|\path(0,0) node(x) {Hello World!};| in order to define a node named |x|.
+%
+\begin{enumerate}
+ \item Once the node |x| has been defined, you can use |(x.|\meta{anchor}|)|
+ wherever you would normally use a normal coordinate. This will yield
+ the position at which the given \meta{anchor} is in the picture. Note
+ that transformations do not apply to this coordinate, that is,
+ |(x.north)| will be the northern anchor of |x| even if you have said
+ |scale=3| or |xshift=4cm|. This is usually what you would expect.
+ \item You can also just use |(x)| as a coordinate. In most cases, this
+ gives the same coordinate as |(x.center)|. Indeed, if the |shape| of
+ |x| is |coordinate|, then |(x)| and |(x.center)| have exactly the same
+ effect.
+
+ However, for most other shapes, some path construction operations like
+ |--| try to be ``clever'' when they are asked to draw a line from such
+ a coordinate or to such a coordinate. When you say |(x)--(1,1)|, the
+ |--| path operation will not draw a line from the center of |x|, but
+ \emph{from the border} of |x| in the direction going towards |(1,1)|.
+ Likewise, |(1,1)--(x)| will also have the line end on the border in the
+ direction coming from |(1,1)|.
+
+ If the specified coordinate is almost identical to the node center, for
+ example |(x)--(0,0)|, no line will be drawn and a warning message will
+ be printed.
+
+ In addition to |--|, the curve-to path operation |..| and the path
+ operations \verb!-|! and \verb!|-! will also handle nodes without
+ anchors correctly. Here is an example, see also
+ Section~\ref{section-node-coordinates}:
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \path (0,0) node (x) {Hello World!}
+ (3,1) node[circle,draw](y) {$\int_1^2 x \mathrm d x$};
+
+ \draw[->,blue] (x) -- (y);
+ \draw[->,red] (x) -| node[near start,below] {label} (y);
+ \draw[->,orange] (x) .. controls +(up:1cm) and +(left:1cm) .. node[above,sloped] {label} (y);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{enumerate}
+
+
+\subsection{Connecting Nodes: Using the Edge Operation}
+\label{section-nodes-edges}
+
+\subsubsection{Basic Syntax of the Edge Operation}
+
+The |edge| operation works like a |to| operation that is added after the main
+path has been drawn, much like a node is added after the main path has been
+drawn. This allows each |edge| to have a different appearance. As the |node|
+operation, an |edge| temporarily suspends the construction of the current path
+and a new path $p$ is constructed. This new path $p$ will be drawn after the
+main path has been drawn. Note that $p$ can be totally different from the main
+path with respect to its options. Also note that if there are several |edge|
+and/or |node| operations in the main path, each creates its own path(s) and
+they are drawn in the order that they are encountered on the main path.
+
+\begin{pathoperation}{edge}{\opt{|[|\meta{options}|]|} \opt{\meta{nodes}} |(|\meta{coordinate}|)|}
+ The effect of the |edge| operation is that after the main path the
+ following path is added to the picture:
+ %
+ \begin{quote}
+ |\path[every edge,|\meta{options}|] (\tikztostart) |\meta{path}|;|
+ \end{quote}
+ %
+ Here, \meta{path} is the |to path|. Note that, unlike the path added by the
+ |to| operation, the |(\tikztostart)| is added before the \meta{path} (which
+ is unnecessary for the |to| operation, since this coordinate is already
+ part of the main path).
+
+ The |\tikztostart| is the last coordinate on the path just before the
+ |edge| operation, just as for the |node| or |to| operations. However, there
+ is one exception to this rule: If the |edge| operation is directly preceded
+ by a |node| operation, then this just-declared node is the start coordinate
+ (and not, as would normally be the case, the coordinate where this
+ just-declared node is placed -- a small, but subtle difference). In this
+ regard, |edge| differs from both |node| and |to|.
+
+ If there are several |edge| operations in a row, the start coordinate is
+ the same for all of them as their target coordinates are not, after all,
+ part of the main path. The start coordinate is, thus, the coordinate
+ preceding the first |edge| operation. This is similar to nodes insofar as
+ the |edge| operation does not modify the current path at all. In
+ particular, it does not change the last coordinate visited, see the
+ following example:
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node (a) at (0:1) {$a$};
+ \node (b) at (90:1) {$b$} edge [->] (a);
+ \node (c) at (180:1) {$c$} edge [->] (a)
+ edge [<-] (b);
+ \node (d) at (270:1) {$d$} edge [->] (a)
+ edge [dotted] (b)
+ edge [<-] (c);
+\end{tikzpicture}
+\end{codeexample}
+
+ A different way of specifying the above graph using the |edge| operation is
+ the following:
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node foreach \name/\angle in {a/0,b/90,c/180,d/270}
+ (\name) at (\angle:1) {$\name$};
+
+ \path[->] (b) edge (a)
+ edge (c)
+ edge [-,dotted] (d)
+ (c) edge (a)
+ edge (d)
+ (d) edge (a);
+\end{tikzpicture}
+\end{codeexample}
+
+ As can be seen, the path of the |edge| operation inherits the options from
+ the main path, but you can locally overrule them.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node foreach \name/\angle in {a/0,b/90,c/180,d/270}
+ (\name) at (\angle:1.5) {$\name$};
+
+ \path[->] (b) edge node[above right] {$5$} (a)
+ edge (c)
+ edge [-,dotted] node[below,sloped] {missing} (d)
+ (c) edge (a)
+ edge (d)
+ (d) edge [red] node[above,sloped] {very}
+ node[below,sloped] {bad} (a);
+\end{tikzpicture}
+\end{codeexample}
+
+ Instead of |every to|, the style |every edge| is installed at the beginning
+ of the main path.
+ %
+ \begin{stylekey}{/tikz/every edge (initially draw)}
+ Executed for each |edge|.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}[every edge/.style={draw,dashed}]
+ \path (0,0) edge (3,2);
+\end{tikzpicture}
+\end{codeexample}
+ \end{stylekey}
+\end{pathoperation}
+
+
+\subsubsection{Nodes on Edges: Quotes Syntax}
+\label{section-edge-quotes}
+
+The standard way of specifying nodes that are placed ``on'' an edge (or on a
+to-path; all of the following is also true for to--paths) is to put node
+specifications after the |edge| keyword, but before the target coordinate.
+Another way is to use the |edge node| option and its friends. Yet another way
+is to use the quotes syntax.
+
+The syntax is essentially the same as for labels added to nodes as described in
+Section~\ref{section-label-quotes} and you also need to load the |quotes|
+library.
+
+In detail, when the |quotes| library is loaded, each time a key--value pair in
+a list of options passed to an |edge| or a |to| path command starts with |"|,
+the key--value pair must actually be a string of the following form:
+%
+\begin{quote}
+ |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}}
+\end{quote}
+%
+This string is transformed into the following:
+%
+\begin{quote}
+ |edge node=node [every edge quotes,|\meta{options}|]{|\meta{text}|}|
+\end{quote}
+%
+As described in Section~\ref{section-label-quotes}, the apostrophe becomes part
+of the \meta{options}, when present.
+
+The following style is important for the placement of the labels:
+
+\begin{stylekey}{/tikz/every edge quotes (initially auto)}
+ This style is |auto| by default, which causes labels specified using the
+ quotes-syntax to be placed next to the edges. Unless the setting of |auto|
+ has been changed, they will be placed to the left.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz \draw (0,0) edge ["left", ->] (2,0);
+\end{codeexample}
+
+ In order to place all labels to the right by default, change this style to
+ |auto=right|:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz [every edge quotes/.style={auto=right}]
+ \draw (0,0) edge ["right", ->] (2,0);
+\end{codeexample}
+
+ To place all nodes ``on'' the edge, just make this style empty (and,
+ possibly, make your labels opaque):
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz [every edge quotes/.style={fill=white,font=\footnotesize}]
+ \draw (0,0) edge ["mid", ->] (2,1);
+\end{codeexample}
+ %
+\end{stylekey}
+
+You may often wish to place some edge nodes to the right of edges and some to
+the left. For this, the special treatment of the apostrophe is particularly
+convenient: Recall that in \tikzname\ there is an option just called |'|, which
+is a shorthand for |swap|. Now, following the closing quotation mark come the
+options of an edge node. Thus, if the closing quotation mark is followed by an
+apostrophe, the |swap| option will be added to the edge label, causing it is be
+placed on the other side. Because of the special treatment, you can even add
+another option like |near end| after the apostrophe without having to add curly
+braces and commas:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz
+ \draw (0,0) edge ["left", "right"',
+ "start" near start,
+ "end"' near end] (4,0);
+\end{codeexample}
+
+In order to modify the distance between the edge labels and the edge, you
+should consider introducing some styles:
+%
+\begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
+\tikz [tight/.style={inner sep=1pt}, loose/.style={inner sep=.7em}]
+ \draw (0,0) edge ["left" tight,
+ "right"' loose,
+ "start" near start] (4,0);
+\end{codeexample}
+
+
+\subsection{Referencing Nodes Outside the Current Picture}
+\label{section-cross-picture-tikz}
+
+\subsubsection{Referencing a Node in a Different Picture}
+
+It is possible (but not quite trivial) to reference nodes in pictures other
+than the current one. This means that you can create a picture and a node
+therein and, later, you can draw a line from some other position to this node.
+
+To reference nodes in different pictures, proceed as follows:
+%
+\begin{enumerate}
+ \item You need to add the |remember picture| option to all pictures that
+ contain nodes that you wish to reference and also to all pictures from
+ which you wish to reference a node in another picture.
+ \item You need to add the |overlay| option to paths or to whole pictures
+ that contain references to nodes in different pictures. (This option
+ switches the computation of the bounding box off.)
+ \item You need to use a driver that supports picture remembering and you
+ need to run \TeX\ twice.
+\end{enumerate}
+%
+(For more details on what is going on behind the scenes, see
+Section~\ref{section-cross-pictures-pgf}.)
+
+Let us have a look at the effect of these options.
+%
+\begin{key}{/tikz/remember picture=\meta{boolean} (initially false)}
+ This option tells \tikzname\ that it should attempt to remember the
+ position of the current picture on the page. This attempt may fail
+ depending on which backend driver is used. Also, even if remembering works,
+ the position may only be available on a second run of \TeX.
+
+ Provided that remembering works, you may consider saying
+ %
+\begin{codeexample}[code only]
+\tikzset{every picture/.append style={remember picture}}
+\end{codeexample}
+ %
+ to make \tikzname\ remember all pictures. This will add one line in the
+ |.aux| file for each picture in your document -- which typically is not
+ very much. Then, you do not have to worry about remembered pictures at all.
+\end{key}
+
+\begin{key}{/tikz/overlay=\meta{boolean} (default true)}
+ This option is mainly intended for use when nodes in other pictures are
+ referenced, but you can also use it in other situations. The effect of this
+ option is that everything within the current scope is not taken into
+ consideration when the bounding box of the current picture is computed.
+
+ You need to specify this option on all paths (or at least on all parts of
+ paths) that contain a reference to a node in another picture. The reason is
+ that, otherwise, \tikzname\ will attempt to make the current picture large
+ enough to encompass \emph{the node in the other picture}. However, on a
+ second run of \TeX\ this will create an even bigger picture, leading to
+ larger and larger pictures. Unless you know what you are doing, I suggest
+ specifying the |overlay| option with all pictures that contain references
+ to other pictures.
+\end{key}
+
+Let us now have a look at a few examples. These examples work only if this
+document is processed with a driver that supports picture remembering.
+\medskip
+
+\noindent%
+\begin{minipage}{\textwidth}
+Inside the current text we place two pictures, containing nodes named |n1| and
+|n2|, using
+%
+\begin{codeexample}[code only]
+\tikz[remember picture] \node[circle,fill=red!50] (n1) {};
+\end{codeexample}
+%
+which yields \tikz[remember picture] \node[circle,fill=red!50] (n1) {};, and
+%
+\begin{codeexample}[code only]
+\tikz[remember picture] \node[fill=blue!50] (n2) {};
+\end{codeexample}
+%
+yielding the node \tikz[remember picture] \node[fill=blue!50] (n2) {};. To
+connect these nodes, we create another picture using the |overlay| option and
+also the |remember picture| option.
+%
+\begin{codeexample}[]
+\begin{tikzpicture}[remember picture,overlay]
+ \draw[->,very thick] (n1) -- (n2);
+\end{tikzpicture}
+\end{codeexample}
+%
+Note that the last picture is seemingly empty. What happens is that it has zero
+size and contains an arrow that lies well outside its bounds. As a last
+example, we connect a node in another picture to the first two nodes. Here, we
+provide the |overlay| option only with the line that we do not wish to count as
+part of the picture.
+%
+\begin{codeexample}[]
+\begin{tikzpicture}[remember picture]
+ \node (c) [circle,draw] {Big circle};
+
+ \draw [overlay,->,very thick,red,opacity=.5]
+ (c) to[bend left] (n1) (n1) -| (n2);
+\end{tikzpicture}
+\end{codeexample}
+\end{minipage}
+
+
+\subsubsection{Referencing the Current Page Node -- Absolute Positioning}
+
+There is a special node called |current page| that can be used to access the
+current page. It is a node of shape rectangle whose |south west| anchor is the
+lower left corner of the page and whose |north east| anchor is the upper right
+corner of the page. While this node is handled in a special way internally, you
+can reference it as if it were defined in some remembered picture other than
+the current one. Thus, by giving the |remember picture| and the |overlay|
+options to a picture, you can position nodes \emph{absolutely} on a page.
+
+The first example places some text in the lower left corner of the current
+page:
+%
+\begin{codeexample}[]
+\begin{tikzpicture}[remember picture,overlay]
+ \node [xshift=1cm,yshift=1cm] at (current page.south west)
+ [text width=7cm,fill=red!20,rounded corners,above right]
+ {
+ This is an absolutely positioned text in the
+ lower left corner. No shipout-hackery is used.
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+The next example adds a circle in the middle of the page.
+%
+\begin{codeexample}[]
+\begin{tikzpicture}[remember picture,overlay]
+ \draw [line width=1mm,opacity=.25]
+ (current page.center) circle (3cm);
+\end{tikzpicture}
+\end{codeexample}
+
+The final example overlays some text over the page (depending on where this
+example is found on the page, the text may also be behind the page).
+%
+\begin{codeexample}[]
+\begin{tikzpicture}[remember picture,overlay]
+ \node [rotate=60,scale=10,text opacity=0.2]
+ at (current page.center) {Example};
+\end{tikzpicture}
+\end{codeexample}
+
+
+\subsection{Late Code and Late Options}
+\label{section-node-also}
+
+All options given to a node only locally affect this one node. While this is a
+blessing in most cases, you may sometimes want to cause options to have effects
+``later'' on. The other way round, you may sometimes note ``only later'' that
+some options should be added to the options of a node. For this, the following
+version of the |node| path command can be used:
+
+\begin{pathoperation}{node also}{\opt{|[|\meta{late options}|]|}|(|\meta{name}|)|}
+ Note that the \meta{name} is compulsory and that \emph{no} text may be
+ given. Also, the ordering of options and node label must be as above.
+
+ The effect of the above is the following effect: The node \meta{name} must
+ already be existing. Now, the \meta{late options} are executed in a local
+ scope. Most of these options will have no effect since you \emph{cannot
+ change the appearance of the node,} that is, you cannot change a red node
+ into a green node using these ``late'' options. However, giving the
+ |append after command| and |prefix after command| options inside the
+ \meta{late options} (directly or indirectly) does have the desired effect:
+ The given path gets executed with the |\tikzlastnode| set to the determined
+ node.
+
+ The net effect of all this is that you can provide, say, the |label| option
+ inside the \meta{options} to a add a label to a node that has already been
+ constructed.
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node [draw,circle] (a) {Hello};
+ \node also [label=above:world] (a);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{pathoperation}
+
+As explained in Section~\ref{section-paths}, you can use the options
+|append after command| and |prefix after command| to add a path after a node.
+The following macro may be useful there:
+%
+\begin{command}{\tikzlastnode}
+ Expands to the last node on the path.
+\end{command}
+
+Instead of the |node also| syntax, you can also use the following option:
+
+\begin{key}{/tikz/late options=\meta{options}}
+ This option can be given on a path (but not as an argument to a |node| path
+ command) and has the same effect as the |node also| path command. Inside
+ the \meta{options}, you should use the |name| option to specify the node
+ for which you wish to add late options:
+ %
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node [draw,circle] (a) {Hello};
+ \path [late options={name=a, label=above:world}];
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{key}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual"
+%%% End: