summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex230
1 files changed, 89 insertions, 141 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex
index 26f9805b6a0..71e1486b1c9 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex
@@ -30,7 +30,7 @@ should look like this, ideally:
%
\begin{quote}
\begin{tikzpicture}
- [node distance=1.3cm,>=stealth',bend angle=45,auto,
+ [node distance=1.3cm,>={Stealth[round]},bend angle=45,auto,
place/.style={circle,thick,draw=blue!75,fill=blue!20,minimum size=6mm},
red place/.style={place,draw=red!75,fill=red!20},
transition/.style={rectangle,thick,draw=black!75,fill=black!20,minimum size=4mm},
@@ -402,22 +402,25 @@ second method is to write the desired name in parentheses after the |node|
operation. Hagen thinks that this second method seems strange, but he will soon
change his opinion.
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
+\begin{codeexample}[setup code,hidden]
+\tikzset{
+ place/.style={circle,draw=blue!50,fill=blue!20,thick,
+ inner sep=0pt,minimum size=6mm},
+ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
+ inner sep=0pt,minimum size=4mm}
+}
+\end{codeexample}
+%
\begin{codeexample}[]
% ... set up styles
\begin{tikzpicture}
- \node (waiting 1) at ( 0,2) [place] {};
- \node (critical 1) at ( 0,1) [place] {};
- \node (semaphore) at ( 0,0) [place] {};
+ \node (waiting 1) at ( 0,2) [place] {};
+ \node (critical 1) at ( 0,1) [place] {};
+ \node (semaphore) at ( 0,0) [place] {};
\node (leave critical) at ( 1,1) [transition] {};
\node (enter critical) at (-1,1) [transition] {};
\end{tikzpicture}
\end{codeexample}
-}
Hagen is pleased to note that the names help in understanding the code. Names
for nodes can be pretty arbitrary, but they should not contain commas, periods,
@@ -430,11 +433,6 @@ can even have multiple option blocks between the |node| and the text in curly
braces, they accumulate. You can rearrange them arbitrarily and perhaps the
following might be preferable:
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
\begin{codeexample}[]
\begin{tikzpicture}
\node[place] (waiting 1) at ( 0,2) {};
@@ -444,7 +442,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
\node[transition] (enter critical) at (-1,1) {};
\end{tikzpicture}
\end{codeexample}
-}
\subsection{Placing Nodes Using Relative Placement}
@@ -457,12 +454,7 @@ below the |waiting 1| node, wherever the |waiting 1| node might be. There are
different ways of achieving this, but the nicest one in Hagen's case is the
|below| option:
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -471,7 +463,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
\node[transition] (enter critical) [left=of critical] {};
\end{tikzpicture}
\end{codeexample}
-}
With the |positioning| library loaded, when an option like |below| is followed
by |of|, then the position of the node is shifted in such a manner that it is
@@ -494,12 +485,8 @@ possible:
\begin{enumerate}
\item Hagen can just add a new node above the |north| anchor of the
|semaphore| node.
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -510,7 +497,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
\node [red,above] at (semaphore.north) {$s\le 3$};
\end{tikzpicture}
\end{codeexample}
-}
%
This is a general approach that will ``always work''.
@@ -524,12 +510,7 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
3$''. Instead of |above| we could also use things like |below left|
before the colon or a number like |60|.
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -539,7 +520,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
\node[transition] (enter critical) [left=of critical] {};
\end{tikzpicture}
\end{codeexample}
-}
%
It is also possible to give multiple |label| options, this causes
multiple labels to be drawn.
@@ -559,12 +539,7 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
|label={[red]above:$s\le3$}|. Since this looks a bit ugly, Hagen
decides to redefine the |every label| style.
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}[every label/.style={red}]
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -574,7 +549,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
\node[transition] (enter critical) [left=of critical] {};
\end{tikzpicture}
\end{codeexample}
-}
\end{enumerate}
@@ -590,12 +564,7 @@ on the left of the node, and so on. To access the coordinate of a node, we use
a coordinate that contains the node's name followed by a dot, followed by the
anchor's name:
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -605,17 +574,11 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
\draw [->] (critical.west) -- (enter critical.east);
\end{tikzpicture}
\end{codeexample}
-}
Next, let us tackle the curve from |waiting| to |enter critical|. This can be
specified using curves and controls:
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -627,7 +590,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
.. (enter critical.north);
\end{tikzpicture}
\end{codeexample}
-}
Hagen sees how he can now add all his edges, but the whole process seems a but
awkward and not very flexible. Again, the code seems to obscure the structure
@@ -636,12 +598,7 @@ of the graphic rather than showing it.
So, let us start improving the code for the edges. First, Hagen can leave out
the anchors:
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -653,7 +610,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
.. (enter critical);
\end{tikzpicture}
\end{codeexample}
-}
Hagen is a bit surprised that this works. After all, how did \tikzname\ know
that the line from |enter critical| to |critical| should actually start on the
@@ -671,12 +627,7 @@ pair of options is useful for Hagen: The pair |in| and |out|. These options
take angles at which a curve should leave or reach the start or target
coordinates. Without these options, a straight line is drawn:
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -687,18 +638,12 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
\draw [->] (waiting) to [out=180,in=90] (enter critical);
\end{tikzpicture}
\end{codeexample}
-}
There is another option for the |to| operation, that is even better suited to
Hagen's problem: The |bend right| option. This option also takes an angle, but
this angle only specifies the angle by which the curve is bent to the right:
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -710,7 +655,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
\draw [->] (enter critical) to [bend right=45] (semaphore);
\end{tikzpicture}
\end{codeexample}
-}
It is now time for Hagen to learn about yet another way of specifying edges:
Using the |edge| path operation. This operation is very similar to the |to|
@@ -721,12 +665,7 @@ consequences. For example, every edge can have its own arrow tips and its own
color and so on and, still, all the edges can be given on the same path. This
allows Hagen to write the following:
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -738,7 +677,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
edge [->,bend right=45] (semaphore);
\end{tikzpicture}
\end{codeexample}
-}
Each |edge| caused a new path to be constructed, consisting of a |to| between
the node |enter critical| and the node following the |edge| command.
@@ -746,17 +684,12 @@ the node |enter critical| and the node following the |edge| command.
The finishing touch is to introduce two styles |pre| and |post| and to use the
|bend angle=45| option to set the bend angle once and for all:
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm}}
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,positioning}}]
% Styles place and transition as before
\begin{tikzpicture}
[bend angle=45,
- pre/.style={<-,shorten <=1pt,>=stealth',semithick},
- post/.style={->,shorten >=1pt,>=stealth',semithick}]
+ pre/.style={<-,shorten <=1pt,>={Stealth[round]},semithick},
+ post/.style={->,shorten >=1pt,>={Stealth[round]},semithick}]
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {};
@@ -772,7 +705,6 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick,
edge [post,bend right] (semaphore);
\end{tikzpicture}
\end{codeexample}
-}
\subsection{Adding Labels Next to Lines}
@@ -783,7 +715,7 @@ Hagen can use \tikzname's automatic node placement: By adding the option
they are not on the curve but next to it. Adding |swap| will mirror the label
with respect to the line. Here is a general example:
%
-{
+% TODOsp: codeexamples: styles not needed here
\begin{codeexample}[]
\begin{tikzpicture}[auto,bend right]
\node (a) at (0:1) {$0^\circ$};
@@ -795,7 +727,6 @@ with respect to the line. Here is a general example:
(c) to node {3} node [swap] {3'} (a);
\end{tikzpicture}
\end{codeexample}
-}
What is happening here? The nodes are given somehow inside the |to| operation!
When this is done, the node is placed on the middle of the curve or line
@@ -807,14 +738,13 @@ For Hagen that |auto| option is not really necessary since the two ``2'' labels
could also easily be placed ``by hand''. However, in a complicated plot with
numerous edges automatic placement can be a blessing.
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm},
-pre/.style={<-,shorten <=1pt,>=stealth',semithick},
-post/.style={->,shorten >=1pt,>=stealth',semithick}}
-\begin{codeexample}[]
+\begin{codeexample}[
+ preamble={\usetikzlibrary{arrows.meta,positioning}},
+ pre={\tikzset{
+ pre/.style={<-,shorten <=1pt,>={Stealth[round]},semithick},
+ post/.style={->,shorten >=1pt,>={Stealth[round]},semithick},
+}},
+]
% Styles as before
\begin{tikzpicture}[bend angle=45]
\node[place] (waiting) {};
@@ -831,7 +761,7 @@ post/.style={->,shorten >=1pt,>=stealth',semithick}}
edge [post,bend right] (semaphore);
\end{tikzpicture}
\end{codeexample}
-}
+% TODOsp: codeexamples: styles and `positioning` are needed up to here
\subsection{Adding the Snaked Line and Multi-Line Text}
@@ -844,7 +774,7 @@ needs to set the two options |decoration=snake| and |decorate| on the path.
This causes all lines of the path to be replaced by snakes. It is also possible
to use snakes only in certain parts of a path, but Hagen will not need this.
%
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
\begin{tikzpicture}
\draw [->,decorate,decoration=snake] (0,0) -- (2,0);
\end{tikzpicture}
@@ -855,7 +785,7 @@ happens to end exactly at the position where the arrow begins. Fortunately,
there is an option that helps here. Also, the snake should be a bit smaller,
which can be influenced by even more options.
%
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
\begin{tikzpicture}
\draw [->,decorate,
decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}]
@@ -868,7 +798,7 @@ since it is a multi-line text. Hagen has two options for this: First, he can
specify an |align=center| and then use the |\\| command to enforce the line
breaks at the desired positions.
%
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
\begin{tikzpicture}
\draw [->,decorate,
decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}]
@@ -885,7 +815,7 @@ breaks at the desired positions.
Instead of specifying the line breaks ``by hand'', Hagen can also specify a
width for the text and let \TeX\ perform the line breaking for him:
%
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
\begin{tikzpicture}
\draw [->,decorate,
decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}]
@@ -908,7 +838,7 @@ coordinates that make up the corners of the rectangle. If Hagen draws the
rectangle first, then he needs to know the exact size of the Petri net -- which
he does not.
-The solution is to use \emph{layers}. When the background library is loaded,
+The solution is to use \emph{layers}. When the |backgrounds| library is loaded,
Hagen can put parts of his picture inside a scope with the
|on background layer| option. Then this part of the picture becomes part of the
layer that is given as an argument to this environment. When the
@@ -924,14 +854,14 @@ the $x$- and $y$-coordinates of the nodes, but it would be nicer to just have
node, causes the node to be resized and shifted such that it exactly covers all
the nodes and coordinates given as parameters to the |fit| option.
%
-{
-\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick,
- inner sep=0pt,minimum size=6mm},
-transition/.style={rectangle,draw=black!50,fill=black!20,thick,
- inner sep=0pt,minimum size=4mm},
-pre/.style={<-,shorten <=1pt,>=stealth',semithick},
-post/.style={->,shorten >=1pt,>=stealth',semithick}}
-\begin{codeexample}[]
+% TODOsp: codeexamples: redo/add styles starting from here
+\begin{codeexample}[
+ preamble={\usetikzlibrary{arrows.meta,backgrounds,fit,positioning}},
+ pre={\tikzset{
+ pre/.style={<-,shorten <=1pt,>={Stealth[round]},semithick},
+ post/.style={->,shorten >=1pt,>={Stealth[round]},semithick},
+}},
+]
% Styles as before
\begin{tikzpicture}[bend angle=45]
\node[place] (waiting) {};
@@ -953,7 +883,6 @@ post/.style={->,shorten >=1pt,>=stealth',semithick}}
\end{scope}
\end{tikzpicture}
\end{codeexample}
-}
\subsection{The Complete Code}
@@ -969,7 +898,7 @@ colors of places and transitions.
%
\begin{codeexample}[code only]
\begin{tikzpicture}
- [node distance=1.3cm,on grid,>=stealth',bend angle=45,auto,
+ [node distance=1.3cm,on grid,>={Stealth[round]},bend angle=45,auto,
every place/.style= {minimum size=6mm,thick,draw=blue!75,fill=blue!20},
every transition/.style={thick,draw=black!75,fill=black!20},
red place/.style= {place,draw=red!75,fill=red!20},
@@ -978,15 +907,18 @@ colors of places and transitions.
Now comes the code for the nets:
%
-{
-\tikzset{
- every place/.style={minimum size=6mm,thick,draw=blue!75,fill=blue!20},
- every transition/.style={thick,draw=black!75,fill=black!20},
- red place/.style={place,draw=red!75,fill=red!20},
- every label/.style={red},
- every picture/.style={on grid,node distance=1.3cm,>=stealth',bend angle=45,auto}}
-\tikzexternaldisable
-\begin{codeexample}[pre=\begin{tikzpicture},post=\end{tikzpicture}]
+\ifpgfmanualexternalize\tikzexternaldisable\fi
+\begin{codeexample}[
+ preamble={\usetikzlibrary{arrows.meta,petri,positioning}},
+ pre={\tikzset{
+ every place/.style={minimum size=6mm,thick,draw=blue!75,fill=blue!20},
+ every transition/.style={thick,draw=black!75,fill=black!20},
+ every label/.style={red},
+ every picture/.style={on grid,node distance=1.3cm,>={Stealth[round]},bend angle=45,auto},
+}%
+\begin{tikzpicture}},
+ post={\end{tikzpicture}},
+]
\node [place,tokens=1] (w1) {};
\node [place] (c1) [below=of w1] {};
\node [place] (s) [below=of c1,label=above:$s\le 3$] {};
@@ -1010,17 +942,20 @@ Now comes the code for the nets:
edge [pre,bend right] (s)
edge [post,bend left] node {2} (w2);
\end{codeexample}
-}
-{
-\tikzset{
-every place/.style={minimum size=6mm,thick,draw=blue!75,fill=blue!20},
-every transition/.style={thick,draw=black!75,fill=black!20},
-red place/.style= {place,draw=red!75,fill=red!20},
-every label/.style={red},
-every picture/.style={on grid,node distance=1.3cm,>=stealth',bend angle=45,auto}}
-\tikzexternaldisable
-\begin{codeexample}[pre=\begin{tikzpicture},post=\end{tikzpicture}]
+\ifpgfmanualexternalize\tikzexternaldisable\fi
+\begin{codeexample}[
+ preamble={\usetikzlibrary{arrows.meta,petri,positioning}},
+ pre={\tikzset{
+ every place/.style={minimum size=6mm,thick,draw=blue!75,fill=blue!20},
+ every transition/.style={thick,draw=black!75,fill=black!20},
+ red place/.style= {place,draw=red!75,fill=red!20},
+ every label/.style={red},
+ every picture/.style={on grid,node distance=1.3cm,>={Stealth[round]},bend angle=45,auto},
+}%
+\begin{tikzpicture}},
+ post={\end{tikzpicture}},
+]
\begin{scope}[xshift=6cm]
\node [place,tokens=1] (w1') {};
\node [place] (c1') [below=of w1'] {};
@@ -1053,7 +988,6 @@ every picture/.style={on grid,node distance=1.3cm,>=stealth',bend angle=45,auto}
edge [post,bend left] node {2} (w2');
\end{scope}
\end{codeexample}
-}
The code for the background and the snake is the following:
%
@@ -1070,3 +1004,17 @@ The code for the background and the snake is the following:
{replacement of the \textcolor{red}{capacity} by \textcolor{red}{two places}};
\end{tikzpicture}
\end{codeexample}
+
+% -----------------------------------------------------------------------------
+% TODOsp: codeexamples: This is needed because -- unlike I thought --
+% `setup code is remembered also outside this file. Thus the changed
+% style of `place` and `transition` are "remembered" in
+% <pgfmanual-en-library-petri.tex>
+\begin{codeexample}[setup code,hidden]
+% from <tikzlibrarypetri.code.tex>
+\tikzset{
+ place/.style={circle,draw,inner sep=0pt,minimum size=5ex,every place},
+ transition/.style={rectangle,draw,inner sep=0pt,minimum size=4mm,every transition},
+}
+\end{codeexample}
+% -----------------------------------------------------------------------------